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