Crate binder

Help

Expand description

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§

Accessor: Rust wrapper around ABinderRpc_Accessor objects for RPC binder service management.
AccessorProvider: Rust wrapper around ABinderRpc_AccessorProvider objects for RPC binder service management.
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§

ConnectionInfo: Socket connection info required for libbinder to connect to a service.
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.
delegate_accessor: 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_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.

Crate binderCopy item path