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] 97 mod binder; 98 mod binder_async; 99 mod error; 100 mod native; 101 mod parcel; 102 mod proxy; 103 mod state; 104 105 use binder_ndk_sys as sys; 106 107 pub use crate::binder_async::{BinderAsyncPool, BoxFuture}; 108 pub use binder::{BinderFeatures, FromIBinder, IBinder, Interface, Strong, Weak}; 109 pub use error::{ExceptionCode, Status, StatusCode}; 110 pub use native::{ 111 add_service, force_lazy_services_persist, is_handling_transaction, register_lazy_service, 112 LazyServiceGuard, 113 }; 114 pub use parcel::{ParcelFileDescriptor, Parcelable, ParcelableHolder}; 115 pub use proxy::{ 116 get_declared_instances, get_interface, get_service, is_declared, wait_for_interface, 117 wait_for_service, DeathRecipient, SpIBinder, WpIBinder, 118 }; 119 pub use state::{ProcessState, ThreadState}; 120 121 /// Binder result containing a [`Status`] on error. 122 pub type Result<T> = std::result::Result<T, Status>; 123 124 /// Advanced Binder APIs needed internally by AIDL or when manually using Binder 125 /// without AIDL. 126 pub mod binder_impl { 127 pub use crate::binder::{ 128 IBinderInternal, InterfaceClass, Remotable, Stability, ToAsyncInterface, ToSyncInterface, 129 TransactionCode, TransactionFlags, FIRST_CALL_TRANSACTION, FLAG_CLEAR_BUF, FLAG_ONEWAY, 130 FLAG_PRIVATE_LOCAL, LAST_CALL_TRANSACTION, 131 }; 132 pub use crate::binder_async::BinderAsyncRuntime; 133 pub use crate::error::status_t; 134 pub use crate::native::Binder; 135 pub use crate::parcel::{ 136 BorrowedParcel, Deserialize, DeserializeArray, DeserializeOption, Parcel, 137 ParcelableMetadata, Serialize, SerializeArray, SerializeOption, NON_NULL_PARCELABLE_FLAG, 138 NULL_PARCELABLE_FLAG, 139 }; 140 pub use crate::proxy::{AssociateClass, Proxy}; 141 } 142 143 /// Unstable, in-development API that only allowlisted clients are allowed to use. 144 #[doc(hidden)] 145 pub mod unstable_api { 146 pub use crate::binder::AsNative; 147 pub use crate::proxy::unstable_api::new_spibinder; 148 pub use crate::sys::AIBinder; 149 pub use crate::sys::AParcel; 150 } 151