Crate binder

Safe Rust interface to Android libbinder.

This crate is primarily designed as an target for a Rust AIDL compiler backend, and should generally not be used directly by users. It is built on top of the binder NDK library to be usable by APEX modules, and therefore only exposes functionality available in the NDK interface.

Example

The following example illustrates how the AIDL backend will use this crate.

use binder::{
    declare_binder_interface, Binder, IBinder, Interface, Remotable, Parcel, SpIBinder,
    StatusCode, TransactionCode,
};

// Generated by AIDL compiler
pub trait ITest: Interface {
    fn test(&self) -> binder::Result<String>;
}

// Creates a new local (native) service object, BnTest, and a remote proxy
// object, BpTest, that are the typed interfaces for their respective ends
// of the binder transaction. Generated by AIDL compiler.
declare_binder_interface! {
    ITest["android.os.ITest"] {
        native: BnTest(on_transact),
        proxy: BpTest,
    }
}

// Generated by AIDL compiler
fn on_transact(
    service: &dyn ITest,
    code: TransactionCode,
    _data: &BorrowedParcel,
    reply: &mut BorrowedParcel,
) -> binder::Result<()> {
    match code {
        SpIBinder::FIRST_CALL_TRANSACTION => {
            reply.write(&service.test()?)?;
            Ok(())
        }
        _ => Err(StatusCode::UNKNOWN_TRANSACTION),
    }
}

// Generated by AIDL compiler
impl ITest for Binder<BnTest> {
    fn test(&self) -> binder::Result<String> {
        self.0.test()
    }
}

// Generated by AIDL compiler
impl ITest for BpTest {
    fn test(&self) -> binder::Result<String> {
       let reply = self
           .as_binder()
           .transact(SpIBinder::FIRST_CALL_TRANSACTION, 0, |_| Ok(()))?;
       reply.read()
    }
}

// User implemented:

// Local implementation of the ITest remotable interface.
struct TestService;

impl Interface for TestService {}

impl ITest for TestService {
    fn test(&self) -> binder::Result<String> {
       Ok("testing service".to_string())
    }
}

Modules

• binder_impl
  Advanced Binder APIs needed internally by AIDL or when manually using Binder without AIDL.

Macros

• declare_binder_enum
  Declare an AIDL enumeration.
• declare_binder_interface
  Declare typed interfaces for a binder object.
• impl_deserialize_for_parcelable
  Implement Deserialize trait and friends for a parcelable
• impl_deserialize_for_unstructured_parcelable
  Implement Deserialize trait and friends for an unstructured parcelable
• impl_serialize_for_parcelable
  Implement Serialize trait and friends for a parcelable
• impl_serialize_for_unstructured_parcelable
  Implements Serialize trait and friends for an unstructured parcelable.

Structs

• BinderFeatures
  The features to enable when creating a native Binder.
• DeathRecipient
  Rust wrapper around DeathRecipient objects.
• LazyServiceGuard
  An RAII object to ensure a process which registers lazy services is not killed. During the lifetime of any of these objects the service manager will not kill the process even if none of its lazy services are in use.
• ParcelFileDescriptor
  Rust version of the Java class android.os.ParcelFileDescriptor
• ParcelableHolder
  A container that can hold any arbitrary Parcelable.
• ProcessState
  Static utility functions to manage Binder process state.
• SpIBinder
  A strong reference to a Binder remote object.
• Status
  High-level binder status object that encapsulates a standard way to keep track of and chain binder errors along with service specific errors.
• Strong
  Strong reference to a binder object
• ThreadState
  Static utility functions to manage Binder thread state.
• Weak
  Weak reference to a binder object
• WpIBinder
  A weak reference to a Binder remote object.

Enums

• ExceptionCode
• StatusCode
  Low-level status codes from Android libutils.

Traits

• BinderAsyncPool
  A thread pool for running binder transactions.
• FromIBinder
  Interface for transforming a generic SpIBinder into a specific remote interface trait.
• IBinder
  Interface of binder local or remote objects.
• Interface
  Super-trait for Binder interfaces.
• IntoBinderResult
  A conversion from std::result::Result<T, E> to binder::Result<T>. If this type is Ok(T), it’s returned as is. If this type is Err(E), E is converted into Status which can be either a general binder exception, or a service-specific exception.
• Parcelable
  Super-trait for structured Binder parcelables, i.e. those generated from AIDL.

Functions

• add_service
  Register a new service with the default service manager.
• check_interface
  Retrieve an existing service for a particular interface. Returns Err(StatusCode::NAME_NOT_FOUND) immediately if the service is not available.
• check_service
  Retrieve an existing service. Returns None immediately if the service is not available.
• force_lazy_services_persist
  Prevent a process which registers lazy services from being shut down even when none of the services is in use.
• get_declared_instances
  Retrieve all declared instances for a particular interface
• get_interfaceDeprecated
  Retrieve an existing service for a particular interface, blocking for a few seconds if it doesn’t yet exist.
• get_serviceDeprecated
  Retrieve an existing service, blocking for a few seconds if it doesn’t yet exist.
• is_declared
  Check if a service is declared (e.g. in a VINTF manifest)
• is_handling_transaction
  Determine whether the current thread is currently executing an incoming transaction.
• register_lazy_service
  Register a dynamic service via the LazyServiceRegistrar.
• wait_for_interface
  Retrieve an existing service for a particular interface, or start it if it is configured as a dynamic service and isn’t yet started.
• wait_for_service
  Retrieve an existing service, or start it if it is configured as a dynamic service and isn’t yet started.

Type Aliases

• BoxFuture
  A type alias for a pinned, boxed future that lets you write shorter code without littering it with Pin and Send bounds.
• Result
  Binder result containing a Status on error.