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(any(trusty, android_ndk)))] 104 mod service; 105 #[cfg(not(any(trusty, android_ndk)))] 106 mod state; 107 #[cfg(not(any(android_vendor, android_ndk, android_vndk)))] 108 mod system_only; 109 110 use binder_ndk_sys as sys; 111 112 pub use crate::binder_async::{BinderAsyncPool, BoxFuture}; 113 pub use binder::{BinderFeatures, FromIBinder, IBinder, Interface, Strong, Weak}; 114 pub use error::{ExceptionCode, IntoBinderResult, Status, StatusCode}; 115 pub use parcel::{ParcelFileDescriptor, Parcelable, ParcelableHolder}; 116 pub use proxy::{DeathRecipient, SpIBinder, WpIBinder}; 117 #[cfg(not(any(trusty, android_ndk)))] 118 pub 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)] 125 pub use service::{get_interface, get_service}; 126 #[cfg(not(any(trusty, android_ndk)))] 127 pub use state::{ProcessState, ThreadState}; 128 #[cfg(not(any(android_vendor, android_vndk, android_ndk)))] 129 pub use system_only::{delegate_accessor, Accessor, AccessorProvider, ConnectionInfo}; 130 131 /// Binder result containing a [`Status`] on error. 132 pub 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. 136 pub 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)] 157 pub 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 } 164