binder/
lib.rs

Help
1/*
2 * Copyright (C) 2020 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17//! Safe Rust interface to Android `libbinder`.
18//!
19//! This crate is primarily designed as an target for a Rust AIDL compiler
20//! backend, and should generally not be used directly by users. It is built on
21//! top of the binder NDK library to be usable by APEX modules, and therefore
22//! only exposes functionality available in the NDK interface.
23//!
24//! # Example
25//!
26//! The following example illustrates how the AIDL backend will use this crate.
27//!
28//! ```
29//! use binder::{
30//!     declare_binder_interface, Binder, IBinder, Interface, Remotable, Parcel, SpIBinder,
31//!     StatusCode, TransactionCode,
32//! };
33//!
34//! // Generated by AIDL compiler
35//! pub trait ITest: Interface {
36//!     fn test(&self) -> binder::Result<String>;
37//! }
38//!
39//! // Creates a new local (native) service object, BnTest, and a remote proxy
40//! // object, BpTest, that are the typed interfaces for their respective ends
41//! // of the binder transaction. Generated by AIDL compiler.
42//! declare_binder_interface! {
43//!     ITest["android.os.ITest"] {
44//!         native: BnTest(on_transact),
45//!         proxy: BpTest,
46//!     }
47//! }
48//!
49//! // Generated by AIDL compiler
50//! fn on_transact(
51//!     service: &dyn ITest,
52//!     code: TransactionCode,
53//!     _data: &BorrowedParcel,
54//!     reply: &mut BorrowedParcel,
55//! ) -> binder::Result<()> {
56//!     match code {
57//!         SpIBinder::FIRST_CALL_TRANSACTION => {
58//!             reply.write(&service.test()?)?;
59//!             Ok(())
60//!         }
61//!         _ => Err(StatusCode::UNKNOWN_TRANSACTION),
62//!     }
63//! }
64//!
65//! // Generated by AIDL compiler
66//! impl ITest for Binder<BnTest> {
67//!     fn test(&self) -> binder::Result<String> {
68//!         self.0.test()
69//!     }
70//! }
71//!
72//! // Generated by AIDL compiler
73//! impl ITest for BpTest {
74//!     fn test(&self) -> binder::Result<String> {
75//!        let reply = self
76//!            .as_binder()
77//!            .transact(SpIBinder::FIRST_CALL_TRANSACTION, 0, |_| Ok(()))?;
78//!        reply.read()
79//!     }
80//! }
81//!
82//! // User implemented:
83//!
84//! // Local implementation of the ITest remotable interface.
85//! struct TestService;
86//!
87//! impl Interface for TestService {}
88//!
89//! impl ITest for TestService {
90//!     fn test(&self) -> binder::Result<String> {
91//!        Ok("testing service".to_string())
92//!     }
93//! }
94//! ```
95
96#[macro_use]
97mod binder;
98mod binder_async;
99mod error;
100mod native;
101mod parcel;
102mod proxy;
103#[cfg(not(any(trusty, android_ndk)))]
104mod service;
105#[cfg(not(any(trusty, android_ndk)))]
106mod state;
107#[cfg(not(any(android_vendor, android_ndk, android_vndk, trusty)))]
108mod system_only;
109
110use binder_ndk_sys as sys;
111
112pub use crate::binder_async::{BinderAsyncPool, BoxFuture};
113pub use binder::{BinderFeatures, FromIBinder, IBinder, Interface, Strong, Weak};
114pub use error::{ExceptionCode, IntoBinderResult, Status, StatusCode};
115pub use parcel::{ParcelFileDescriptor, Parcelable, ParcelableHolder};
116pub use proxy::{DeathRecipient, SpIBinder, WpIBinder};
117#[cfg(not(any(trusty, android_ndk)))]
118pub use service::{
119    add_service, check_interface, check_service, force_lazy_services_persist,
120    get_declared_instances, is_declared, is_handling_transaction, register_lazy_service,
121    wait_for_interface, wait_for_service, LazyServiceGuard,
122};
123#[cfg(not(any(trusty, android_ndk)))]
124#[allow(deprecated)]
125pub use service::{get_interface, get_service};
126#[cfg(not(any(trusty, android_ndk)))]
127pub use state::{ProcessState, ThreadState};
128#[cfg(not(any(android_vendor, android_vndk, android_ndk, trusty)))]
129pub use system_only::{delegate_accessor, Accessor, AccessorProvider, ConnectionInfo};
130
131/// Binder result containing a [`Status`] on error.
132pub type Result<T> = std::result::Result<T, Status>;
133
134/// Advanced Binder APIs needed internally by AIDL or when manually using Binder
135/// without AIDL.
136pub mod binder_impl {
137    pub use crate::binder::{
138        IBinderInternal, InterfaceClass, LocalStabilityType, Remotable, Stability, StabilityType,
139        ToAsyncInterface, ToSyncInterface, TransactionCode, TransactionFlags, VintfStabilityType,
140        FIRST_CALL_TRANSACTION, FLAG_ONEWAY, LAST_CALL_TRANSACTION,
141    };
142    #[cfg(not(android_ndk))]
143    pub use crate::binder::{FLAG_CLEAR_BUF, FLAG_PRIVATE_LOCAL};
144    pub use crate::binder_async::BinderAsyncRuntime;
145    pub use crate::error::status_t;
146    pub use crate::native::Binder;
147    pub use crate::parcel::{
148        BorrowedParcel, Deserialize, DeserializeArray, DeserializeOption, Parcel,
149        ParcelableMetadata, Serialize, SerializeArray, SerializeOption, UnstructuredParcelable,
150        NON_NULL_PARCELABLE_FLAG, NULL_PARCELABLE_FLAG,
151    };
152    pub use crate::proxy::{AssociateClass, Proxy};
153}
154
155/// Unstable, in-development API that only allowlisted clients are allowed to use.
156#[doc(hidden)]
157pub mod unstable_api {
158    pub use crate::binder::AsNative;
159    pub use crate::error::status_result;
160    pub use crate::proxy::unstable_api::new_spibinder;
161    pub use crate::sys::AIBinder;
162    pub use crate::sys::AParcel;
163}
binder/lib.rs

binder/
lib.rs
