Struct Binder

#[repr(C)]
pub struct Binder<T: Remotable> { /* private fields */ }

Rust wrapper around Binder remotable objects.

Implements the C++ BBinder class, and therefore implements the C++ IBinder interface.

Implementations

impl<T: Remotable> Binder<T>

pub fn new(rust_object: T) -> Binder<T>

Create a new Binder remotable object with default stability

This moves the rust_object into an owned Box and Binder will manage its lifetime.

pub fn new_with_stability(rust_object: T, stability: Stability) -> Binder<T>

Create a new Binder remotable object with the given stability

This moves the rust_object into an owned Box and Binder will manage its lifetime.

pub fn set_extension( &mut self, extension: &mut SpIBinder, ) -> Result<(), StatusCode>

Set the extension of a binder interface. This allows a downstream developer to add an extension to an interface without modifying its interface file. This should be called immediately when the object is created before it is passed to another thread.

Examples

For instance, imagine if we have this Binder AIDL interface definition: interface IFoo { void doFoo(); }

If an unrelated owner (perhaps in a downstream codebase) wants to make a change to the interface, they have two options:

1. Historical option that has proven to be BAD! Only the original author of an interface should change an interface. If someone downstream wants additional functionality, they should not ever change the interface or use this method.

   BAD TO DO:  interface IFoo {                       BAD TO DO
   BAD TO DO:      void doFoo();                      BAD TO DO
   BAD TO DO: +    void doBar(); // adding a method   BAD TO DO
   BAD TO DO:  }                                      BAD TO DO

2. Option that this method enables! Leave the original interface unchanged (do not change IFoo!). Instead, create a new AIDL interface in a downstream package:

   package com.<name>; // new functionality in a new package
   interface IBar { void doBar(); }

   When registering the interface, add:

   let mut foo: Binder<MyFoo> = Binder::new(my_foo); // class in AOSP codebase
   let bar: Binder<MyBar> = Binder::new(my_bar);     // custom extension class
   foo.set_extension(&mut bar.as_binder());          // use method in Binder

   Then, clients of IFoo can get this extension:

   if let Some(barBinder) = binder.get_extension()? {
       let bar = BpBar::new(barBinder)
           .expect("Extension was not of type IBar");
   } else {
       // There was no extension
   }

pub fn get_descriptor() -> &'static str

Retrieve the interface descriptor string for this object’s Binder interface.

Trait Implementations

impl<T: Remotable> Deref for Binder<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T: Remotable> Drop for Binder<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: Remotable> Interface for Binder<T>

fn as_binder(&self) -> SpIBinder

Converts the local remotable object into a generic SpIBinder reference.

The resulting SpIBinder will hold its own strong reference to this remotable object, which will prevent the object from being dropped while the SpIBinder is alive.

fn dump( &self, _writer: &mut dyn Write, _args: &[&CStr], ) -> Result<(), StatusCode>

Dump transaction handler for this Binder object.

impl<B: Remotable> Serialize for Binder<B>

fn serialize(&self, parcel: &mut BorrowedParcel<'_>) -> Result<(), StatusCode>

Serialize this instance into the given crate::parcel::Parcel.

impl<B: Remotable> TryFrom<SpIBinder> for Binder<B>

type Error = android_c_interface_StatusCode

The type returned in the event of a conversion error.

fn try_from(ibinder: SpIBinder) -> Result<Self, StatusCode>

Performs the conversion.

impl<T: Remotable> Send for Binder<T>

Safety:

A Binder<T> is a pair of unique owning pointers to two values:

• a C++ ABBinder which the C++ API guarantees can be passed between threads
• a Rust object which implements Remotable; this trait requires Send + Sync

Both pointers are unique (never escape the Binder<T> object and are not copied) so we can essentially treat Binder<T> as a box-like containing the two objects; the box-like object inherits Send from the two inner values, similarly to how Box<T> is Send if T is Send.

impl<T: Remotable> Sync for Binder<T>

Safety:

A Binder<T> is a pair of unique owning pointers to two values:

• a C++ ABBinder which is thread-safe, i.e. Send + Sync
• a Rust object which implements Remotable; this trait requires Send + Sync

ABBinder contains an immutable mUserData pointer, which is actually a pointer to a boxed T: Remotable, which is Sync. ABBinder also contains a mutable pointer to its class, but mutation of this field is controlled by a mutex and it is only allowed to be set once, therefore we can concurrently access this field safely. ABBinder inherits from BBinder, which is also thread-safe. Thus ABBinder is thread-safe.

Both pointers are unique (never escape the Binder<T> object and are not copied) so we can essentially treat Binder<T> as a box-like containing the two objects; the box-like object inherits Sync from the two inner values, similarly to how Box<T> is Sync if T is Sync.