Crate binder_ndk

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_serialize_for_parcelable
  Implement Serialize trait and friends for a 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 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

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.
• Parcelable
  Super-trait for Binder parcelables.

Functions

• add_service
  Register a new service with the default service manager.
• 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_interface
  Retrieve an existing service for a particular interface, blocking for a few seconds if it doesn’t yet exist.
• get_service
  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 Definitions

• 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.