Crate rsbinder

Expand description

A pure Rust implementation of Android Binder IPC mechanism.

This library provides a complete implementation of the Android Binder protocol for inter-process communication (IPC) on Linux and Android systems. It enables services to communicate across process boundaries with type safety and efficiency.

§Core Components

Binder: Core binder object and transaction handling
Parcel: Serialization/deserialization for IPC data
Proxy: Client-side interface for remote services
Native: Server-side service implementation utilities
ProcessState: Process-level binder state management
ServiceManager: Service discovery and registration

§Basic Usage

This library works with AIDL (Android Interface Definition Language) files to generate type-safe Rust bindings for IPC services.

§Setting up an AIDL-based Service

First, create an AIDL interface file (aidl/hello/IHello.aidl):

package hello;

interface IHello {
    String echo(in String message);
}

Add a build.rs file to generate Rust bindings:

rsbinder_aidl::Builder::new()
    .source(PathBuf::from("aidl/hello/IHello.aidl"))
    .output(PathBuf::from("hello.rs"))
    .generate()
    .unwrap();

In your Cargo.toml, add the build dependency:

[build-dependencies]
rsbinder-aidl = "0.4"

§Implementing the Service

use rsbinder::*;

// Include the generated code
include!(concat!(env!("OUT_DIR"), "/hello.rs"));
pub use crate::hello::IHello::*;

// Implement the service
struct HelloService;

impl Interface for HelloService {}

impl IHello for HelloService {
    fn echo(&self, message: &str) -> rsbinder::status::Result<String> {
        Ok(format!("Echo: {}", message))
    }
}

// Initialize the process state
ProcessState::init_default();

// Start the thread pool
ProcessState::start_thread_pool();

// Register your service
let service = BnHello::new_binder(HelloService);
hub::add_service("hello_service", service.as_binder())?;

println!("Hello service started");

// Join the thread pool to handle requests
ProcessState::join_thread_pool();

§Creating a Client

use rsbinder::*;

// Include the same generated code
include!(concat!(env!("OUT_DIR"), "/hello.rs"));
pub use crate::hello::IHello::*;

// Initialize the process state
ProcessState::init_default();

// Get service from service manager
let service = hub::get_service("hello_service")?;
let hello_service = BpHello::new(service)?;

// Call remote method
let result = hello_service.echo("Hello, World!")?;
println!("Service response: {}", result);

§License

Licensed under Apache License, Version 2.0.

§References

AIDL
Binder

Re-exports§

pub use binder_async::BinderAsyncPool;
pub use binder_async::BinderAsyncRuntime;
pub use binder_async::BoxFuture;
pub use error::Result;
pub use error::StatusCode;
pub use file_descriptor::ParcelFileDescriptor;
pub use parcel::Parcel;
pub use parcelable_holder::ParcelableHolder;
pub use status::ExceptionCode;
pub use status::Status;
pub use native::*;
pub use parcelable::*;
pub use proxy::*;

Modules§

binder_async: Async binder runtime support Async support for binder operations.
binderfs: BinderFS filesystem utilities BinderFS filesystem utilities.
error: Error types and result handling Error handling and status codes for binder operations.
file_descriptor: File descriptor wrapper for IPC File descriptor wrapper for binder IPC.
hub: Service hub and manager implementations
native: Native service implementation helpers Native service implementation utilities.
parcel: Data serialization for IPC Data serialization and deserialization for binder IPC.
parcelable: Parcelable trait for serializable types Parcelable trait and utilities for serializable types.
parcelable_holder: Holder for parcelable objects Generic container for parcelable objects.
proxy: Client proxy for remote services Client proxy for remote binder services.
status: Status and exception handling Status and exception handling for binder operations.
thread_state: Thread-local binder state Thread-local binder state management.

Macros§

__declare_binder_interface
declare_binder_enum: Declare an AIDL enumeration.
declare_binder_interface: Declare a binder interface.
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§

ProcessState
SIBinder: Strong reference to a binder object.
Strong: Strong reference to a binder object
TokioRuntime: Wrapper around Tokio runtime types for providing a runtime to a binder server.
WIBinder: Weak reference to a binder object.
Weak: Weak reference to a binder object

Enums§

Stability: Interface stability promise
Tokio: Use the Tokio spawn_blocking pool with AIDL.

Constants§

DEBUG_PID_TRANSACTION
DEFAULT_BINDERFS_PATH: Default path to the binderfs mount point
DEFAULT_BINDER_CONTROL_PATH: Default path to the binder control device
DEFAULT_BINDER_PATH: Default path to the binder device
DUMP_TRANSACTION
EXTENSION_TRANSACTION
FIRST_CALL_TRANSACTION
FLAG_CLEAR_BUF: Corresponds to TF_CLEAR_BUF – clear transaction buffers after call is made.
FLAG_ONEWAY: Corresponds to TF_ONE_WAY – an asynchronous call.
FLAG_PRIVATE_LOCAL: Set to the vendor flag if we are building for the VNDK, 0 otherwise
FLAG_PRIVATE_VENDOR
INTERFACE_HEADER
INTERFACE_TRANSACTION
LAST_CALL_TRANSACTION
LIKE_TRANSACTION
PING_TRANSACTION
SET_RPC_CLIENT_TRANSACTION
SHELL_COMMAND_TRANSACTION
START_RECORDING_TRANSACTION
STOP_RECORDING_TRANSACTION
SYSPROPS_TRANSACTION
TWEET_TRANSACTION

Traits§

DeathRecipient: Interface for receiving a notification when a binder object is no longer valid.
FromIBinder: Trait for converting a generic Binder object into a specific Binder
IBinder: Core interface for binder objects, both local and remote.
Interface: Base trait for all binder interfaces.
Remotable: Trait for local services that can be exposed via binder IPC.
ToAsyncInterface: Implemented by sync interfaces to specify what the associated async interface is. Generic to handle the fact that async interfaces are generic over a thread pool.
ToSyncInterface: Implemented by async interfaces to specify what the associated sync interface is.
Transactable: A transactable object that can be used to process Binder commands.

Functions§

get_interface: Retrieve an existing service for a particular interface, sleeping for a few seconds if it doesn’t yet exist.

Type Aliases§

TransactionCode: Binder action to perform.
TransactionFlags: Additional operation flags.

Crate rsbinderCopy item path