blob: 321b422185452999c45e5ed21121866836fdc019 [file] [log] [blame]
Stephen Crane2a3c2502020-06-16 17:48:35 -07001/*
2 * Copyright (C) 2020 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17//! Trait definitions for binder objects
18
Stephen Craneddb3e6d2020-12-18 13:27:22 -080019use crate::error::{status_t, Result, StatusCode};
Stephen Crane2a3c2502020-06-16 17:48:35 -070020use crate::parcel::Parcel;
Stephen Craneddb3e6d2020-12-18 13:27:22 -080021use crate::proxy::{DeathRecipient, SpIBinder, WpIBinder};
Stephen Crane2a3c2502020-06-16 17:48:35 -070022use crate::sys;
23
Stephen Craneddb3e6d2020-12-18 13:27:22 -080024use std::borrow::Borrow;
25use std::cmp::Ordering;
Stephen Crane669deb62020-09-10 17:31:39 -070026use std::ffi::{c_void, CStr, CString};
Stephen Craneddb3e6d2020-12-18 13:27:22 -080027use std::fmt;
28use std::marker::PhantomData;
29use std::ops::Deref;
Stephen Crane669deb62020-09-10 17:31:39 -070030use std::os::raw::c_char;
Stephen Crane2a3c2502020-06-16 17:48:35 -070031use std::os::unix::io::AsRawFd;
32use std::ptr;
33
34/// Binder action to perform.
35///
Andrew Walbran12400d82021-03-04 17:04:34 +000036/// This must be a number between [`FIRST_CALL_TRANSACTION`] and
37/// [`LAST_CALL_TRANSACTION`].
Stephen Crane2a3c2502020-06-16 17:48:35 -070038pub type TransactionCode = u32;
39
40/// Additional operation flags.
41///
Andrew Walbran12400d82021-03-04 17:04:34 +000042/// `FLAG_*` values.
Stephen Crane2a3c2502020-06-16 17:48:35 -070043pub type TransactionFlags = u32;
44
45/// Super-trait for Binder interfaces.
46///
47/// This trait allows conversion of a Binder interface trait object into an
48/// IBinder object for IPC calls. All Binder remotable interface (i.e. AIDL
49/// interfaces) must implement this trait.
50///
51/// This is equivalent `IInterface` in C++.
Stephen Craneddb3e6d2020-12-18 13:27:22 -080052pub trait Interface: Send {
Stephen Crane2a3c2502020-06-16 17:48:35 -070053 /// Convert this binder object into a generic [`SpIBinder`] reference.
54 fn as_binder(&self) -> SpIBinder {
55 panic!("This object was not a Binder object and cannot be converted into an SpIBinder.")
56 }
57}
58
Stephen Craneff7f03a2021-02-25 16:04:22 -080059/// Interface stability promise
60///
61/// An interface can promise to be a stable vendor interface ([`Vintf`]), or
62/// makes no stability guarantees ([`Local`]). [`Local`] is
63/// currently the default stability.
64pub enum Stability {
65 /// Default stability, visible to other modules in the same compilation
66 /// context (e.g. modules on system.img)
67 Local,
68
69 /// A Vendor Interface Object, which promises to be stable
70 Vintf,
71}
72
73impl Default for Stability {
74 fn default() -> Self {
75 Stability::Local
76 }
77}
78
Stephen Crane2a3c2502020-06-16 17:48:35 -070079/// A local service that can be remotable via Binder.
80///
81/// An object that implement this interface made be made into a Binder service
82/// via `Binder::new(object)`.
83///
84/// This is a low-level interface that should normally be automatically
85/// generated from AIDL via the [`declare_binder_interface!`] macro. When using
86/// the AIDL backend, users need only implement the high-level AIDL-defined
87/// interface. The AIDL compiler then generates a container struct that wraps
88/// the user-defined service and implements `Remotable`.
Andrei Homescu2c674b02020-08-07 22:12:27 -070089pub trait Remotable: Send + Sync {
Stephen Crane2a3c2502020-06-16 17:48:35 -070090 /// The Binder interface descriptor string.
91 ///
92 /// This string is a unique identifier for a Binder interface, and should be
93 /// the same between all implementations of that interface.
94 fn get_descriptor() -> &'static str;
95
96 /// Handle and reply to a request to invoke a transaction on this object.
97 ///
98 /// `reply` may be [`None`] if the sender does not expect a reply.
99 fn on_transact(&self, code: TransactionCode, data: &Parcel, reply: &mut Parcel) -> Result<()>;
100
101 /// Retrieve the class of this remote object.
102 ///
103 /// This method should always return the same InterfaceClass for the same
104 /// type.
105 fn get_class() -> InterfaceClass;
106}
107
Andrew Walbran12400d82021-03-04 17:04:34 +0000108/// First transaction code available for user commands (inclusive)
109pub const FIRST_CALL_TRANSACTION: TransactionCode = sys::FIRST_CALL_TRANSACTION;
110/// Last transaction code available for user commands (inclusive)
111pub const LAST_CALL_TRANSACTION: TransactionCode = sys::LAST_CALL_TRANSACTION;
112
113/// Corresponds to TF_ONE_WAY -- an asynchronous call.
114pub const FLAG_ONEWAY: TransactionFlags = sys::FLAG_ONEWAY;
115/// Corresponds to TF_CLEAR_BUF -- clear transaction buffers after call is made.
116pub const FLAG_CLEAR_BUF: TransactionFlags = sys::FLAG_CLEAR_BUF;
Stephen Craneff7f03a2021-02-25 16:04:22 -0800117/// Set to the vendor flag if we are building for the VNDK, 0 otherwise
118pub const FLAG_PRIVATE_LOCAL: TransactionFlags = sys::FLAG_PRIVATE_LOCAL;
Andrew Walbran12400d82021-03-04 17:04:34 +0000119
120/// Internal interface of binder local or remote objects for making
121/// transactions.
Stephen Crane2a3c2502020-06-16 17:48:35 -0700122///
Andrew Walbran12400d82021-03-04 17:04:34 +0000123/// This trait corresponds to the parts of the interface of the C++ `IBinder`
124/// class which are internal implementation details.
125pub trait IBinderInternal: IBinder {
Stephen Crane2a3c2502020-06-16 17:48:35 -0700126 /// Is this object still alive?
127 fn is_binder_alive(&self) -> bool;
128
129 /// Send a ping transaction to this object
130 fn ping_binder(&mut self) -> Result<()>;
131
Janis Danisevskis798a09a2020-08-18 08:35:38 -0700132 /// Indicate that the service intends to receive caller security contexts.
133 fn set_requesting_sid(&mut self, enable: bool);
134
Stephen Crane2a3c2502020-06-16 17:48:35 -0700135 /// Dump this object to the given file handle
136 fn dump<F: AsRawFd>(&mut self, fp: &F, args: &[&str]) -> Result<()>;
137
138 /// Get a new interface that exposes additional extension functionality, if
139 /// available.
140 fn get_extension(&mut self) -> Result<Option<SpIBinder>>;
141
142 /// Perform a generic operation with the object.
143 ///
144 /// # Arguments
145 /// * `code` - Transaction code for the operation
146 /// * `data` - [`Parcel`] with input data
147 /// * `reply` - Optional [`Parcel`] for reply data
148 /// * `flags` - Transaction flags, e.g. marking the transaction as
Andrew Walbran12400d82021-03-04 17:04:34 +0000149 /// asynchronous ([`FLAG_ONEWAY`](FLAG_ONEWAY))
Stephen Crane2a3c2502020-06-16 17:48:35 -0700150 fn transact<F: FnOnce(&mut Parcel) -> Result<()>>(
151 &self,
152 code: TransactionCode,
153 flags: TransactionFlags,
154 input_callback: F,
155 ) -> Result<Parcel>;
Andrew Walbran12400d82021-03-04 17:04:34 +0000156}
Stephen Crane2a3c2502020-06-16 17:48:35 -0700157
Andrew Walbran12400d82021-03-04 17:04:34 +0000158/// Interface of binder local or remote objects.
159///
160/// This trait corresponds to the parts of the interface of the C++ `IBinder`
161/// class which are public.
162pub trait IBinder {
Stephen Crane2a3c2502020-06-16 17:48:35 -0700163 /// Register the recipient for a notification if this binder
164 /// goes away. If this binder object unexpectedly goes away
165 /// (typically because its hosting process has been killed),
Andrew Walbran12400d82021-03-04 17:04:34 +0000166 /// then the `DeathRecipient`'s callback will be called.
Stephen Crane2a3c2502020-06-16 17:48:35 -0700167 ///
168 /// You will only receive death notifications for remote binders,
169 /// as local binders by definition can't die without you dying as well.
170 /// Trying to use this function on a local binder will result in an
171 /// INVALID_OPERATION code being returned and nothing happening.
172 ///
173 /// This link always holds a weak reference to its recipient.
Stephen Crane2a3c2502020-06-16 17:48:35 -0700174 fn link_to_death(&mut self, recipient: &mut DeathRecipient) -> Result<()>;
175
176 /// Remove a previously registered death notification.
177 /// The recipient will no longer be called if this object
178 /// dies.
179 fn unlink_to_death(&mut self, recipient: &mut DeathRecipient) -> Result<()>;
180}
181
182/// Opaque reference to the type of a Binder interface.
183///
184/// This object encapsulates the Binder interface descriptor string, along with
185/// the binder transaction callback, if the class describes a local service.
186///
187/// A Binder remotable object may only have a single interface class, and any
188/// given object can only be associated with one class. Two objects with
189/// different classes are incompatible, even if both classes have the same
190/// interface descriptor.
191#[derive(Copy, Clone, PartialEq, Eq)]
192pub struct InterfaceClass(*const sys::AIBinder_Class);
193
194impl InterfaceClass {
195 /// Get a Binder NDK `AIBinder_Class` pointer for this object type.
196 ///
197 /// Note: the returned pointer will not be constant. Calling this method
198 /// multiple times for the same type will result in distinct class
199 /// pointers. A static getter for this value is implemented in
200 /// [`declare_binder_interface!`].
201 pub fn new<I: InterfaceClassMethods>() -> InterfaceClass {
202 let descriptor = CString::new(I::get_descriptor()).unwrap();
203 let ptr = unsafe {
204 // Safety: `AIBinder_Class_define` expects a valid C string, and
205 // three valid callback functions, all non-null pointers. The C
206 // string is copied and need not be valid for longer than the call,
207 // so we can drop it after the call. We can safely assign null to
208 // the onDump and handleShellCommand callbacks as long as the class
209 // pointer was non-null. Rust None for a Option<fn> is guaranteed to
210 // be a NULL pointer. Rust retains ownership of the pointer after it
211 // is defined.
212 let class = sys::AIBinder_Class_define(
213 descriptor.as_ptr(),
214 Some(I::on_create),
215 Some(I::on_destroy),
216 Some(I::on_transact),
217 );
218 if class.is_null() {
219 panic!("Expected non-null class pointer from AIBinder_Class_define!");
220 }
221 sys::AIBinder_Class_setOnDump(class, None);
222 sys::AIBinder_Class_setHandleShellCommand(class, None);
223 class
224 };
225 InterfaceClass(ptr)
226 }
227
228 /// Construct an `InterfaceClass` out of a raw, non-null `AIBinder_Class`
229 /// pointer.
230 ///
231 /// # Safety
232 ///
233 /// This function is safe iff `ptr` is a valid, non-null pointer to an
234 /// `AIBinder_Class`.
235 pub(crate) unsafe fn from_ptr(ptr: *const sys::AIBinder_Class) -> InterfaceClass {
236 InterfaceClass(ptr)
237 }
Stephen Crane669deb62020-09-10 17:31:39 -0700238
239 /// Get the interface descriptor string of this class.
240 pub fn get_descriptor(&self) -> String {
241 unsafe {
242 // SAFETY: The descriptor returned by AIBinder_Class_getDescriptor
243 // is always a two-byte null terminated sequence of u16s. Thus, we
244 // can continue reading from the pointer until we hit a null value,
245 // and this pointer can be a valid slice if the slice length is <=
246 // the number of u16 elements before the null terminator.
247
248 let raw_descriptor: *const c_char = sys::AIBinder_Class_getDescriptor(self.0);
Andrew Walbran12400d82021-03-04 17:04:34 +0000249 CStr::from_ptr(raw_descriptor)
250 .to_str()
Stephen Crane669deb62020-09-10 17:31:39 -0700251 .expect("Expected valid UTF-8 string from AIBinder_Class_getDescriptor")
252 .into()
253 }
254 }
Stephen Crane2a3c2502020-06-16 17:48:35 -0700255}
256
257impl From<InterfaceClass> for *const sys::AIBinder_Class {
258 fn from(class: InterfaceClass) -> *const sys::AIBinder_Class {
259 class.0
260 }
261}
262
Stephen Craneddb3e6d2020-12-18 13:27:22 -0800263/// Strong reference to a binder object
264pub struct Strong<I: FromIBinder + ?Sized>(Box<I>);
265
266impl<I: FromIBinder + ?Sized> Strong<I> {
267 /// Create a new strong reference to the provided binder object
268 pub fn new(binder: Box<I>) -> Self {
269 Self(binder)
270 }
271
272 /// Construct a new weak reference to this binder
273 pub fn downgrade(this: &Strong<I>) -> Weak<I> {
274 Weak::new(this)
275 }
276}
277
278impl<I: FromIBinder + ?Sized> Clone for Strong<I> {
279 fn clone(&self) -> Self {
280 // Since we hold a strong reference, we should always be able to create
281 // a new strong reference to the same interface type, so try_from()
282 // should never fail here.
283 FromIBinder::try_from(self.0.as_binder()).unwrap()
284 }
285}
286
287impl<I: FromIBinder + ?Sized> Borrow<I> for Strong<I> {
288 fn borrow(&self) -> &I {
289 &self.0
290 }
291}
292
293impl<I: FromIBinder + ?Sized> AsRef<I> for Strong<I> {
294 fn as_ref(&self) -> &I {
295 &self.0
296 }
297}
298
299impl<I: FromIBinder + ?Sized> Deref for Strong<I> {
300 type Target = I;
301
302 fn deref(&self) -> &Self::Target {
303 &self.0
304 }
305}
306
307impl<I: FromIBinder + fmt::Debug + ?Sized> fmt::Debug for Strong<I> {
308 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
309 fmt::Debug::fmt(&**self, f)
310 }
311}
312
313impl<I: FromIBinder + ?Sized> Ord for Strong<I> {
314 fn cmp(&self, other: &Self) -> Ordering {
315 self.0.as_binder().cmp(&other.0.as_binder())
316 }
317}
318
319impl<I: FromIBinder + ?Sized> PartialOrd for Strong<I> {
320 fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
321 self.0.as_binder().partial_cmp(&other.0.as_binder())
322 }
323}
324
325impl<I: FromIBinder + ?Sized> PartialEq for Strong<I> {
326 fn eq(&self, other: &Self) -> bool {
327 self.0.as_binder().eq(&other.0.as_binder())
328 }
329}
330
331impl<I: FromIBinder + ?Sized> Eq for Strong<I> {}
332
333/// Weak reference to a binder object
334#[derive(Debug)]
335pub struct Weak<I: FromIBinder + ?Sized> {
336 weak_binder: WpIBinder,
337 interface_type: PhantomData<I>,
338}
339
340impl<I: FromIBinder + ?Sized> Weak<I> {
341 /// Construct a new weak reference from a strong reference
342 fn new(binder: &Strong<I>) -> Self {
343 let weak_binder = binder.as_binder().downgrade();
344 Weak {
345 weak_binder,
346 interface_type: PhantomData,
347 }
348 }
349
350 /// Upgrade this weak reference to a strong reference if the binder object
351 /// is still alive
352 pub fn upgrade(&self) -> Result<Strong<I>> {
353 self.weak_binder
354 .promote()
355 .ok_or(StatusCode::DEAD_OBJECT)
356 .and_then(FromIBinder::try_from)
357 }
358}
359
360impl<I: FromIBinder + ?Sized> Clone for Weak<I> {
361 fn clone(&self) -> Self {
362 Self {
363 weak_binder: self.weak_binder.clone(),
364 interface_type: PhantomData,
365 }
366 }
367}
368
369impl<I: FromIBinder + ?Sized> Ord for Weak<I> {
370 fn cmp(&self, other: &Self) -> Ordering {
371 self.weak_binder.cmp(&other.weak_binder)
372 }
373}
374
375impl<I: FromIBinder + ?Sized> PartialOrd for Weak<I> {
376 fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
377 self.weak_binder.partial_cmp(&other.weak_binder)
378 }
379}
380
381impl<I: FromIBinder + ?Sized> PartialEq for Weak<I> {
382 fn eq(&self, other: &Self) -> bool {
383 self.weak_binder == other.weak_binder
384 }
385}
386
387impl<I: FromIBinder + ?Sized> Eq for Weak<I> {}
388
Stephen Crane2a3c2502020-06-16 17:48:35 -0700389/// Create a function implementing a static getter for an interface class.
390///
391/// Each binder interface (i.e. local [`Remotable`] service or remote proxy
392/// [`Interface`]) must have global, static class that uniquely identifies
393/// it. This macro implements an [`InterfaceClass`] getter to simplify these
394/// implementations.
395///
396/// The type of a structure that implements [`InterfaceClassMethods`] must be
397/// passed to this macro. For local services, this should be `Binder<Self>`
398/// since [`Binder`] implements [`InterfaceClassMethods`].
399///
400/// # Examples
401///
402/// When implementing a local [`Remotable`] service `ExampleService`, the
403/// `get_class` method is required in the [`Remotable`] impl block. This macro
404/// should be used as follows to implement this functionality:
405///
406/// ```rust
407/// impl Remotable for ExampleService {
408/// fn get_descriptor() -> &'static str {
409/// "android.os.IExampleInterface"
410/// }
411///
412/// fn on_transact(
413/// &self,
414/// code: TransactionCode,
415/// data: &Parcel,
416/// reply: &mut Parcel,
417/// ) -> Result<()> {
418/// // ...
419/// }
420///
421/// binder_fn_get_class!(Binder<Self>);
422/// }
423/// ```
424macro_rules! binder_fn_get_class {
425 ($class:ty) => {
426 binder_fn_get_class!($crate::InterfaceClass::new::<$class>());
427 };
428
429 ($constructor:expr) => {
430 fn get_class() -> $crate::InterfaceClass {
431 static CLASS_INIT: std::sync::Once = std::sync::Once::new();
432 static mut CLASS: Option<$crate::InterfaceClass> = None;
433
434 CLASS_INIT.call_once(|| unsafe {
435 // Safety: This assignment is guarded by the `CLASS_INIT` `Once`
436 // variable, and therefore is thread-safe, as it can only occur
437 // once.
438 CLASS = Some($constructor);
439 });
440 unsafe {
441 // Safety: The `CLASS` variable can only be mutated once, above,
442 // and is subsequently safe to read from any thread.
443 CLASS.unwrap()
444 }
445 }
446 };
447}
448
449pub trait InterfaceClassMethods {
450 /// Get the interface descriptor string for this object type.
451 fn get_descriptor() -> &'static str
452 where
453 Self: Sized;
454
455 /// Called during construction of a new `AIBinder` object of this interface
456 /// class.
457 ///
458 /// The opaque pointer parameter will be the parameter provided to
459 /// `AIBinder_new`. Returns an opaque userdata to be associated with the new
460 /// `AIBinder` object.
461 ///
462 /// # Safety
463 ///
464 /// Callback called from C++. The parameter argument provided to
465 /// `AIBinder_new` must match the type expected here. The `AIBinder` object
466 /// will take ownership of the returned pointer, which it will free via
467 /// `on_destroy`.
468 unsafe extern "C" fn on_create(args: *mut c_void) -> *mut c_void;
469
470 /// Called when a transaction needs to be processed by the local service
471 /// implementation.
472 ///
473 /// # Safety
474 ///
475 /// Callback called from C++. The `binder` parameter must be a valid pointer
476 /// to a binder object of this class with userdata initialized via this
477 /// class's `on_create`. The parcel parameters must be valid pointers to
478 /// parcel objects.
479 unsafe extern "C" fn on_transact(
480 binder: *mut sys::AIBinder,
481 code: u32,
482 data: *const sys::AParcel,
483 reply: *mut sys::AParcel,
484 ) -> status_t;
485
486 /// Called whenever an `AIBinder` object is no longer referenced and needs
487 /// to be destroyed.
488 ///
489 /// # Safety
490 ///
491 /// Callback called from C++. The opaque pointer parameter must be the value
492 /// returned by `on_create` for this class. This function takes ownership of
493 /// the provided pointer and destroys it.
494 unsafe extern "C" fn on_destroy(object: *mut c_void);
495}
496
497/// Interface for transforming a generic SpIBinder into a specific remote
498/// interface trait.
499///
500/// # Example
501///
502/// For Binder interface `IFoo`, the following implementation should be made:
503/// ```no_run
504/// # use binder::{FromIBinder, SpIBinder, Result};
505/// # trait IFoo {}
506/// impl FromIBinder for dyn IFoo {
507/// fn try_from(ibinder: SpIBinder) -> Result<Box<Self>> {
508/// // ...
509/// # Err(binder::StatusCode::OK)
510/// }
511/// }
512/// ```
Stephen Craneddb3e6d2020-12-18 13:27:22 -0800513pub trait FromIBinder: Interface {
Stephen Crane2a3c2502020-06-16 17:48:35 -0700514 /// Try to interpret a generic Binder object as this interface.
515 ///
516 /// Returns a trait object for the `Self` interface if this object
517 /// implements that interface.
Stephen Craneddb3e6d2020-12-18 13:27:22 -0800518 fn try_from(ibinder: SpIBinder) -> Result<Strong<Self>>;
Stephen Crane2a3c2502020-06-16 17:48:35 -0700519}
520
521/// Trait for transparent Rust wrappers around android C++ native types.
522///
523/// The pointer return by this trait's methods should be immediately passed to
524/// C++ and not stored by Rust. The pointer is valid only as long as the
525/// underlying C++ object is alive, so users must be careful to take this into
526/// account, as Rust cannot enforce this.
527///
528/// # Safety
529///
530/// For this trait to be a correct implementation, `T` must be a valid android
531/// C++ type. Since we cannot constrain this via the type system, this trait is
532/// marked as unsafe.
533pub unsafe trait AsNative<T> {
534 /// Return a pointer to the native version of `self`
535 fn as_native(&self) -> *const T;
536
537 /// Return a mutable pointer to the native version of `self`
538 fn as_native_mut(&mut self) -> *mut T;
539}
540
541unsafe impl<T, V: AsNative<T>> AsNative<T> for Option<V> {
542 fn as_native(&self) -> *const T {
543 self.as_ref().map_or(ptr::null(), |v| v.as_native())
544 }
545
546 fn as_native_mut(&mut self) -> *mut T {
547 self.as_mut().map_or(ptr::null_mut(), |v| v.as_native_mut())
548 }
549}
550
551/// Declare typed interfaces for a binder object.
552///
553/// Given an interface trait and descriptor string, create a native and remote
554/// proxy wrapper for this interface. The native service object (`$native`)
555/// implements `Remotable` and will dispatch to the function `$on_transact` to
556/// handle transactions. The typed proxy object (`$proxy`) wraps remote binder
557/// objects for this interface and can optionally contain additional fields.
558///
559/// Assuming the interface trait is `Interface`, `$on_transact` function must
560/// have the following type:
561///
562/// ```
563/// # use binder::{Interface, TransactionCode, Parcel};
564/// # trait Placeholder {
565/// fn on_transact(
566/// service: &dyn Interface,
567/// code: TransactionCode,
568/// data: &Parcel,
569/// reply: &mut Parcel,
570/// ) -> binder::Result<()>;
571/// # }
572/// ```
573///
574/// # Examples
575///
576/// The following example declares the local service type `BnServiceManager` and
577/// a remote proxy type `BpServiceManager` (the `n` and `p` stand for native and
578/// proxy respectively) for the `IServiceManager` Binder interface. The
579/// interfaces will be identified by the descriptor string
580/// "android.os.IServiceManager". The local service will dispatch transactions
581/// using the provided function, `on_transact`.
582///
583/// ```
584/// use binder::{declare_binder_interface, Binder, Interface, TransactionCode, Parcel};
585///
586/// pub trait IServiceManager: Interface {
587/// // remote methods...
588/// }
589///
590/// declare_binder_interface! {
591/// IServiceManager["android.os.IServiceManager"] {
592/// native: BnServiceManager(on_transact),
593/// proxy: BpServiceManager,
594/// }
595/// }
596///
597/// fn on_transact(
598/// service: &dyn IServiceManager,
599/// code: TransactionCode,
600/// data: &Parcel,
601/// reply: &mut Parcel,
602/// ) -> binder::Result<()> {
603/// // ...
604/// Ok(())
605/// }
606///
607/// impl IServiceManager for BpServiceManager {
608/// // parceling/unparceling code for the IServiceManager emitted here
609/// }
610///
611/// impl IServiceManager for Binder<BnServiceManager> {
612/// // Forward calls to local implementation
613/// }
614/// ```
615#[macro_export]
616macro_rules! declare_binder_interface {
617 {
618 $interface:path[$descriptor:expr] {
619 native: $native:ident($on_transact:path),
620 proxy: $proxy:ident,
621 }
622 } => {
623 $crate::declare_binder_interface! {
624 $interface[$descriptor] {
625 native: $native($on_transact),
626 proxy: $proxy {},
Stephen Craneff7f03a2021-02-25 16:04:22 -0800627 stability: $crate::Stability::default(),
628 }
629 }
630 };
631
632 {
633 $interface:path[$descriptor:expr] {
634 native: $native:ident($on_transact:path),
635 proxy: $proxy:ident,
636 stability: $stability:expr,
637 }
638 } => {
639 $crate::declare_binder_interface! {
640 $interface[$descriptor] {
641 native: $native($on_transact),
642 proxy: $proxy {},
643 stability: $stability,
Stephen Crane2a3c2502020-06-16 17:48:35 -0700644 }
645 }
646 };
647
648 {
649 $interface:path[$descriptor:expr] {
650 native: $native:ident($on_transact:path),
651 proxy: $proxy:ident {
652 $($fname:ident: $fty:ty = $finit:expr),*
653 },
654 }
655 } => {
656 $crate::declare_binder_interface! {
657 $interface[$descriptor] {
Stephen Craneff7f03a2021-02-25 16:04:22 -0800658 native: $native($on_transact),
659 proxy: $proxy {
660 $($fname: $fty = $finit),*
661 },
662 stability: $crate::Stability::default(),
663 }
664 }
665 };
666
667 {
668 $interface:path[$descriptor:expr] {
669 native: $native:ident($on_transact:path),
670 proxy: $proxy:ident {
671 $($fname:ident: $fty:ty = $finit:expr),*
672 },
673 stability: $stability:expr,
674 }
675 } => {
676 $crate::declare_binder_interface! {
677 $interface[$descriptor] {
Stephen Crane2a3c2502020-06-16 17:48:35 -0700678 @doc[concat!("A binder [`Remotable`]($crate::Remotable) that holds an [`", stringify!($interface), "`] object.")]
679 native: $native($on_transact),
680 @doc[concat!("A binder [`Proxy`]($crate::Proxy) that holds an [`", stringify!($interface), "`] remote interface.")]
681 proxy: $proxy {
682 $($fname: $fty = $finit),*
683 },
Stephen Craneff7f03a2021-02-25 16:04:22 -0800684 stability: $stability,
Stephen Crane2a3c2502020-06-16 17:48:35 -0700685 }
686 }
687 };
688
689 {
690 $interface:path[$descriptor:expr] {
691 @doc[$native_doc:expr]
692 native: $native:ident($on_transact:path),
693
694 @doc[$proxy_doc:expr]
695 proxy: $proxy:ident {
696 $($fname:ident: $fty:ty = $finit:expr),*
697 },
Stephen Craneff7f03a2021-02-25 16:04:22 -0800698
699 stability: $stability:expr,
Stephen Crane2a3c2502020-06-16 17:48:35 -0700700 }
701 } => {
702 #[doc = $proxy_doc]
703 pub struct $proxy {
704 binder: $crate::SpIBinder,
705 $($fname: $fty,)*
706 }
707
708 impl $crate::Interface for $proxy {
709 fn as_binder(&self) -> $crate::SpIBinder {
710 self.binder.clone()
711 }
712 }
713
714 impl $crate::Proxy for $proxy
715 where
716 $proxy: $interface,
717 {
718 fn get_descriptor() -> &'static str {
719 $descriptor
720 }
721
722 fn from_binder(mut binder: $crate::SpIBinder) -> $crate::Result<Self> {
Stephen Crane669deb62020-09-10 17:31:39 -0700723 Ok(Self { binder, $($fname: $finit),* })
Stephen Crane2a3c2502020-06-16 17:48:35 -0700724 }
725 }
726
727 #[doc = $native_doc]
728 #[repr(transparent)]
729 pub struct $native(Box<dyn $interface + Sync + Send + 'static>);
730
731 impl $native {
732 /// Create a new binder service.
Stephen Craneddb3e6d2020-12-18 13:27:22 -0800733 pub fn new_binder<T: $interface + Sync + Send + 'static>(inner: T) -> $crate::Strong<dyn $interface> {
Stephen Craneff7f03a2021-02-25 16:04:22 -0800734 let binder = $crate::Binder::new_with_stability($native(Box::new(inner)), $stability);
Stephen Craneddb3e6d2020-12-18 13:27:22 -0800735 $crate::Strong::new(Box::new(binder))
Stephen Crane2a3c2502020-06-16 17:48:35 -0700736 }
737 }
738
739 impl $crate::Remotable for $native {
740 fn get_descriptor() -> &'static str {
741 $descriptor
742 }
743
744 fn on_transact(&self, code: $crate::TransactionCode, data: &$crate::Parcel, reply: &mut $crate::Parcel) -> $crate::Result<()> {
Andrei Homescu32814372020-08-20 15:36:08 -0700745 match $on_transact(&*self.0, code, data, reply) {
746 // The C++ backend converts UNEXPECTED_NULL into an exception
747 Err($crate::StatusCode::UNEXPECTED_NULL) => {
748 let status = $crate::Status::new_exception(
749 $crate::ExceptionCode::NULL_POINTER,
750 None,
751 );
752 reply.write(&status)
753 },
754 result => result
755 }
Stephen Crane2a3c2502020-06-16 17:48:35 -0700756 }
757
758 fn get_class() -> $crate::InterfaceClass {
759 static CLASS_INIT: std::sync::Once = std::sync::Once::new();
760 static mut CLASS: Option<$crate::InterfaceClass> = None;
761
762 CLASS_INIT.call_once(|| unsafe {
763 // Safety: This assignment is guarded by the `CLASS_INIT` `Once`
764 // variable, and therefore is thread-safe, as it can only occur
765 // once.
766 CLASS = Some($crate::InterfaceClass::new::<$crate::Binder<$native>>());
767 });
768 unsafe {
769 // Safety: The `CLASS` variable can only be mutated once, above,
770 // and is subsequently safe to read from any thread.
771 CLASS.unwrap()
772 }
773 }
774 }
775
776 impl $crate::FromIBinder for dyn $interface {
Stephen Craneddb3e6d2020-12-18 13:27:22 -0800777 fn try_from(mut ibinder: $crate::SpIBinder) -> $crate::Result<$crate::Strong<dyn $interface>> {
Stephen Crane2a3c2502020-06-16 17:48:35 -0700778 use $crate::AssociateClass;
Stephen Crane669deb62020-09-10 17:31:39 -0700779
780 let existing_class = ibinder.get_class();
781 if let Some(class) = existing_class {
782 if class != <$native as $crate::Remotable>::get_class() &&
783 class.get_descriptor() == <$native as $crate::Remotable>::get_descriptor()
784 {
785 // The binder object's descriptor string matches what we
786 // expect. We still need to treat this local or already
787 // associated object as remote, because we can't cast it
788 // into a Rust service object without a matching class
789 // pointer.
Stephen Craneddb3e6d2020-12-18 13:27:22 -0800790 return Ok($crate::Strong::new(Box::new(<$proxy as $crate::Proxy>::from_binder(ibinder)?)));
Stephen Crane669deb62020-09-10 17:31:39 -0700791 }
Stephen Crane2a3c2502020-06-16 17:48:35 -0700792 }
793
Stephen Crane669deb62020-09-10 17:31:39 -0700794 if ibinder.associate_class(<$native as $crate::Remotable>::get_class()) {
795 let service: $crate::Result<$crate::Binder<$native>> =
796 std::convert::TryFrom::try_from(ibinder.clone());
797 if let Ok(service) = service {
798 // We were able to associate with our expected class and
799 // the service is local.
Stephen Craneddb3e6d2020-12-18 13:27:22 -0800800 return Ok($crate::Strong::new(Box::new(service)));
Stephen Crane669deb62020-09-10 17:31:39 -0700801 } else {
802 // Service is remote
Stephen Craneddb3e6d2020-12-18 13:27:22 -0800803 return Ok($crate::Strong::new(Box::new(<$proxy as $crate::Proxy>::from_binder(ibinder)?)));
Stephen Crane669deb62020-09-10 17:31:39 -0700804 }
Matthew Maurerf6b9ad92020-12-03 19:27:25 +0000805 }
Stephen Crane669deb62020-09-10 17:31:39 -0700806
807 Err($crate::StatusCode::BAD_TYPE.into())
Stephen Crane2a3c2502020-06-16 17:48:35 -0700808 }
809 }
810
811 impl $crate::parcel::Serialize for dyn $interface + '_
812 where
Stephen Craned58bce02020-07-07 12:26:02 -0700813 dyn $interface: $crate::Interface
Stephen Crane2a3c2502020-06-16 17:48:35 -0700814 {
815 fn serialize(&self, parcel: &mut $crate::parcel::Parcel) -> $crate::Result<()> {
816 let binder = $crate::Interface::as_binder(self);
817 parcel.write(&binder)
818 }
819 }
820
821 impl $crate::parcel::SerializeOption for dyn $interface + '_ {
822 fn serialize_option(this: Option<&Self>, parcel: &mut $crate::parcel::Parcel) -> $crate::Result<()> {
823 parcel.write(&this.map($crate::Interface::as_binder))
824 }
825 }
Andrei Homescu2e3c1472020-08-11 16:35:40 -0700826
827 impl std::fmt::Debug for dyn $interface {
828 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
829 f.pad(stringify!($interface))
830 }
831 }
Andrei Homescu64ebd132020-08-07 22:12:48 -0700832
Stephen Craneddb3e6d2020-12-18 13:27:22 -0800833 /// Convert a &dyn $interface to Strong<dyn $interface>
Andrei Homescu64ebd132020-08-07 22:12:48 -0700834 impl std::borrow::ToOwned for dyn $interface {
Stephen Craneddb3e6d2020-12-18 13:27:22 -0800835 type Owned = $crate::Strong<dyn $interface>;
Andrei Homescu64ebd132020-08-07 22:12:48 -0700836 fn to_owned(&self) -> Self::Owned {
837 self.as_binder().into_interface()
838 .expect(concat!("Error cloning interface ", stringify!($interface)))
839 }
840 }
Stephen Crane2a3c2502020-06-16 17:48:35 -0700841 };
842}
Andrei Homescu00eca712020-09-09 18:57:40 -0700843
844/// Declare an AIDL enumeration.
845///
846/// This is mainly used internally by the AIDL compiler.
847#[macro_export]
848macro_rules! declare_binder_enum {
849 {
850 $enum:ident : $backing:ty {
851 $( $name:ident = $value:expr, )*
852 }
853 } => {
854 #[derive(Debug, Default, Copy, Clone, PartialOrd, Ord, PartialEq, Eq, Hash)]
855 pub struct $enum(pub $backing);
856 impl $enum {
857 $( pub const $name: Self = Self($value); )*
858 }
859
860 impl $crate::parcel::Serialize for $enum {
861 fn serialize(&self, parcel: &mut $crate::parcel::Parcel) -> $crate::Result<()> {
862 parcel.write(&self.0)
863 }
864 }
865
866 impl $crate::parcel::SerializeArray for $enum {
867 fn serialize_array(slice: &[Self], parcel: &mut $crate::parcel::Parcel) -> $crate::Result<()> {
868 let v: Vec<$backing> = slice.iter().map(|x| x.0).collect();
869 <$backing as binder::parcel::SerializeArray>::serialize_array(&v[..], parcel)
870 }
871 }
872
873 impl $crate::parcel::Deserialize for $enum {
874 fn deserialize(parcel: &$crate::parcel::Parcel) -> $crate::Result<Self> {
875 parcel.read().map(Self)
876 }
877 }
878
879 impl $crate::parcel::DeserializeArray for $enum {
880 fn deserialize_array(parcel: &$crate::parcel::Parcel) -> $crate::Result<Option<Vec<Self>>> {
881 let v: Option<Vec<$backing>> =
882 <$backing as binder::parcel::DeserializeArray>::deserialize_array(parcel)?;
883 Ok(v.map(|v| v.into_iter().map(Self).collect()))
884 }
885 }
886 };
887}