blob: 83553d793be8d0a6518f8ee83672be1c2be0f5a0 [file] [log] [blame]
Stephen Crane2a3c2502020-06-16 17:48:35 -07001/*
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//! Rust API for interacting with a remote binder service.
18
19use crate::binder::{
Andrew Walbran12400d82021-03-04 17:04:34 +000020 AsNative, FromIBinder, IBinder, IBinderInternal, Interface, InterfaceClass, Strong,
21 TransactionCode, TransactionFlags,
Stephen Crane2a3c2502020-06-16 17:48:35 -070022};
23use crate::error::{status_result, Result, StatusCode};
24use crate::parcel::{
Alice Ryhl8618c482021-11-09 15:35:35 +000025 Parcel, BorrowedParcel, Deserialize, DeserializeArray, DeserializeOption, Serialize, SerializeArray, SerializeOption,
Stephen Crane2a3c2502020-06-16 17:48:35 -070026};
27use crate::sys;
28
Stephen Craneddb3e6d2020-12-18 13:27:22 -080029use std::cmp::Ordering;
Andrew Walbran12400d82021-03-04 17:04:34 +000030use std::convert::TryInto;
Stephen Crane2a3c2502020-06-16 17:48:35 -070031use std::ffi::{c_void, CString};
Andrei Homescu2e3c1472020-08-11 16:35:40 -070032use std::fmt;
Alice Ryhlea9d9d22021-08-27 07:51:30 +000033use std::mem;
Stephen Crane2a3c2502020-06-16 17:48:35 -070034use std::os::unix::io::AsRawFd;
35use std::ptr;
Alice Ryhlea9d9d22021-08-27 07:51:30 +000036use std::sync::Arc;
Stephen Crane2a3c2502020-06-16 17:48:35 -070037
38/// A strong reference to a Binder remote object.
39///
40/// This struct encapsulates the generic C++ `sp<IBinder>` class. This wrapper
41/// is untyped; typed interface access is implemented by the AIDL compiler.
Alice Ryhl8dde9bc2021-08-16 16:57:10 +000042pub struct SpIBinder(ptr::NonNull<sys::AIBinder>);
Stephen Crane2a3c2502020-06-16 17:48:35 -070043
Andrei Homescu2e3c1472020-08-11 16:35:40 -070044impl fmt::Debug for SpIBinder {
45 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
46 f.pad("SpIBinder")
47 }
48}
49
Stephen Crane2a3c2502020-06-16 17:48:35 -070050/// # Safety
51///
Stephen Cranef03fe3d2021-06-25 15:05:00 -070052/// An `SpIBinder` is an immutable handle to a C++ IBinder, which is thread-safe
Stephen Crane2a3c2502020-06-16 17:48:35 -070053unsafe impl Send for SpIBinder {}
54
Stephen Cranef03fe3d2021-06-25 15:05:00 -070055/// # Safety
56///
57/// An `SpIBinder` is an immutable handle to a C++ IBinder, which is thread-safe
58unsafe impl Sync for SpIBinder {}
59
Stephen Crane2a3c2502020-06-16 17:48:35 -070060impl SpIBinder {
61 /// Create an `SpIBinder` wrapper object from a raw `AIBinder` pointer.
62 ///
63 /// # Safety
64 ///
65 /// This constructor is safe iff `ptr` is a null pointer or a valid pointer
66 /// to an `AIBinder`.
67 ///
68 /// In the non-null case, this method conceptually takes ownership of a strong
69 /// reference to the object, so `AIBinder_incStrong` must have been called
70 /// on the pointer before passing it to this constructor. This is generally
71 /// done by Binder NDK methods that return an `AIBinder`, but care should be
72 /// taken to ensure this invariant.
73 ///
74 /// All `SpIBinder` objects that are constructed will hold a valid pointer
75 /// to an `AIBinder`, which will remain valid for the entire lifetime of the
76 /// `SpIBinder` (we keep a strong reference, and only decrement on drop).
77 pub(crate) unsafe fn from_raw(ptr: *mut sys::AIBinder) -> Option<Self> {
Alice Ryhl8dde9bc2021-08-16 16:57:10 +000078 ptr::NonNull::new(ptr).map(Self)
Stephen Crane2a3c2502020-06-16 17:48:35 -070079 }
80
Stephen Craned58bce02020-07-07 12:26:02 -070081 /// Extract a raw `AIBinder` pointer from this wrapper.
82 ///
83 /// This method should _only_ be used for testing. Do not try to use the NDK
84 /// interface directly for anything else.
85 ///
86 /// # Safety
87 ///
88 /// The resulting pointer is valid only as long as the SpIBinder is alive.
89 /// The SpIBinder object retains ownership of the AIBinder and the caller
90 /// should not attempt to free the returned pointer.
91 pub unsafe fn as_raw(&self) -> *mut sys::AIBinder {
Alice Ryhl8dde9bc2021-08-16 16:57:10 +000092 self.0.as_ptr()
Stephen Craned58bce02020-07-07 12:26:02 -070093 }
94
Stephen Crane2a3c2502020-06-16 17:48:35 -070095 /// Return true if this binder object is hosted in a different process than
96 /// the current one.
97 pub fn is_remote(&self) -> bool {
98 unsafe {
99 // Safety: `SpIBinder` guarantees that it always contains a valid
100 // `AIBinder` pointer.
101 sys::AIBinder_isRemote(self.as_native())
102 }
103 }
104
105 /// Try to convert this Binder object into a trait object for the given
106 /// Binder interface.
107 ///
108 /// If this object does not implement the expected interface, the error
109 /// `StatusCode::BAD_TYPE` is returned.
Stephen Craneddb3e6d2020-12-18 13:27:22 -0800110 pub fn into_interface<I: FromIBinder + Interface + ?Sized>(self) -> Result<Strong<I>> {
Stephen Crane2a3c2502020-06-16 17:48:35 -0700111 FromIBinder::try_from(self)
112 }
113
114 /// Return the interface class of this binder object, if associated with
115 /// one.
Stephen Crane669deb62020-09-10 17:31:39 -0700116 pub fn get_class(&mut self) -> Option<InterfaceClass> {
Stephen Crane2a3c2502020-06-16 17:48:35 -0700117 unsafe {
118 // Safety: `SpIBinder` guarantees that it always contains a valid
119 // `AIBinder` pointer. `AIBinder_getClass` returns either a null
120 // pointer or a valid pointer to an `AIBinder_Class`. After mapping
121 // null to None, we can safely construct an `InterfaceClass` if the
122 // pointer was non-null.
123 let class = sys::AIBinder_getClass(self.as_native_mut());
124 class.as_ref().map(|p| InterfaceClass::from_ptr(p))
125 }
126 }
Andrew Walbran8fe3ecc2020-12-15 11:29:58 +0000127
128 /// Creates a new weak reference to this binder object.
129 pub fn downgrade(&mut self) -> WpIBinder {
130 WpIBinder::new(self)
131 }
Stephen Crane2a3c2502020-06-16 17:48:35 -0700132}
133
Victor Hsiehd35d31d2021-06-03 11:24:31 -0700134pub mod unstable_api {
135 use super::{sys, SpIBinder};
136
137 /// A temporary API to allow the client to create a `SpIBinder` from a `sys::AIBinder`. This is
138 /// needed to bridge RPC binder, which doesn't have Rust API yet.
139 /// TODO(b/184872979): remove once the Rust API is created.
140 ///
141 /// # Safety
142 ///
143 /// See `SpIBinder::from_raw`.
144 pub unsafe fn new_spibinder(ptr: *mut sys::AIBinder) -> Option<SpIBinder> {
145 SpIBinder::from_raw(ptr)
146 }
147}
148
Stephen Crane2a3c2502020-06-16 17:48:35 -0700149/// An object that can be associate with an [`InterfaceClass`].
150pub trait AssociateClass {
151 /// Check if this object is a valid object for the given interface class
152 /// `I`.
153 ///
154 /// Returns `Some(self)` if this is a valid instance of the interface, and
155 /// `None` otherwise.
156 ///
157 /// Classes constructed by `InterfaceClass` are unique per type, so
158 /// repeatedly calling this method for the same `InterfaceClass` is allowed.
159 fn associate_class(&mut self, class: InterfaceClass) -> bool;
160}
161
162impl AssociateClass for SpIBinder {
163 fn associate_class(&mut self, class: InterfaceClass) -> bool {
164 unsafe {
165 // Safety: `SpIBinder` guarantees that it always contains a valid
166 // `AIBinder` pointer. An `InterfaceClass` can always be converted
167 // into a valid `AIBinder_Class` pointer, so these parameters are
168 // always safe.
169 sys::AIBinder_associateClass(self.as_native_mut(), class.into())
170 }
171 }
172}
173
Stephen Craneddb3e6d2020-12-18 13:27:22 -0800174impl Ord for SpIBinder {
175 fn cmp(&self, other: &Self) -> Ordering {
176 let less_than = unsafe {
177 // Safety: SpIBinder always holds a valid `AIBinder` pointer, so
178 // this pointer is always safe to pass to `AIBinder_lt` (null is
179 // also safe to pass to this function, but we should never do that).
Alice Ryhl8dde9bc2021-08-16 16:57:10 +0000180 sys::AIBinder_lt(self.0.as_ptr(), other.0.as_ptr())
Stephen Craneddb3e6d2020-12-18 13:27:22 -0800181 };
182 let greater_than = unsafe {
183 // Safety: SpIBinder always holds a valid `AIBinder` pointer, so
184 // this pointer is always safe to pass to `AIBinder_lt` (null is
185 // also safe to pass to this function, but we should never do that).
Alice Ryhl8dde9bc2021-08-16 16:57:10 +0000186 sys::AIBinder_lt(other.0.as_ptr(), self.0.as_ptr())
Stephen Craneddb3e6d2020-12-18 13:27:22 -0800187 };
188 if !less_than && !greater_than {
189 Ordering::Equal
190 } else if less_than {
191 Ordering::Less
192 } else {
193 Ordering::Greater
194 }
195 }
196}
197
198impl PartialOrd for SpIBinder {
199 fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
200 Some(self.cmp(other))
201 }
202}
203
Stephen Crane994a0f02020-08-11 14:47:29 -0700204impl PartialEq for SpIBinder {
205 fn eq(&self, other: &Self) -> bool {
Alice Ryhl8dde9bc2021-08-16 16:57:10 +0000206 ptr::eq(self.0.as_ptr(), other.0.as_ptr())
Stephen Crane994a0f02020-08-11 14:47:29 -0700207 }
208}
209
210impl Eq for SpIBinder {}
211
Stephen Crane2a3c2502020-06-16 17:48:35 -0700212impl Clone for SpIBinder {
213 fn clone(&self) -> Self {
214 unsafe {
215 // Safety: Cloning a strong reference must increment the reference
216 // count. We are guaranteed by the `SpIBinder` constructor
217 // invariants that `self.0` is always a valid `AIBinder` pointer.
Alice Ryhl8dde9bc2021-08-16 16:57:10 +0000218 sys::AIBinder_incStrong(self.0.as_ptr());
Stephen Crane2a3c2502020-06-16 17:48:35 -0700219 }
220 Self(self.0)
221 }
222}
223
224impl Drop for SpIBinder {
225 // We hold a strong reference to the IBinder in SpIBinder and need to give up
226 // this reference on drop.
227 fn drop(&mut self) {
228 unsafe {
229 // Safety: SpIBinder always holds a valid `AIBinder` pointer, so we
230 // know this pointer is safe to pass to `AIBinder_decStrong` here.
231 sys::AIBinder_decStrong(self.as_native_mut());
232 }
233 }
234}
235
Andrew Walbran12400d82021-03-04 17:04:34 +0000236impl<T: AsNative<sys::AIBinder>> IBinderInternal for T {
Alice Ryhl8618c482021-11-09 15:35:35 +0000237 fn prepare_transact(&self) -> Result<Parcel> {
Stephen Crane2a3c2502020-06-16 17:48:35 -0700238 let mut input = ptr::null_mut();
239 let status = unsafe {
240 // Safety: `SpIBinder` guarantees that `self` always contains a
241 // valid pointer to an `AIBinder`. It is safe to cast from an
242 // immutable pointer to a mutable pointer here, because
243 // `AIBinder_prepareTransaction` only calls immutable `AIBinder`
244 // methods but the parameter is unfortunately not marked as const.
245 //
246 // After the call, input will be either a valid, owned `AParcel`
247 // pointer, or null.
248 sys::AIBinder_prepareTransaction(self.as_native() as *mut sys::AIBinder, &mut input)
249 };
Alice Ryhlfeba6ca2021-08-19 10:47:04 +0000250
Stephen Crane2a3c2502020-06-16 17:48:35 -0700251 status_result(status)?;
Alice Ryhlfeba6ca2021-08-19 10:47:04 +0000252
253 unsafe {
Stephen Crane2a3c2502020-06-16 17:48:35 -0700254 // Safety: At this point, `input` is either a valid, owned `AParcel`
Alice Ryhl268458c2021-09-15 12:56:10 +0000255 // pointer, or null. `OwnedParcel::from_raw` safely handles both cases,
Stephen Crane2a3c2502020-06-16 17:48:35 -0700256 // taking ownership of the parcel.
Alice Ryhl8618c482021-11-09 15:35:35 +0000257 Parcel::from_raw(input).ok_or(StatusCode::UNEXPECTED_NULL)
Alice Ryhlfeba6ca2021-08-19 10:47:04 +0000258 }
259 }
260
261 fn submit_transact(
262 &self,
263 code: TransactionCode,
Alice Ryhl8618c482021-11-09 15:35:35 +0000264 data: Parcel,
Alice Ryhlfeba6ca2021-08-19 10:47:04 +0000265 flags: TransactionFlags,
Alice Ryhl8618c482021-11-09 15:35:35 +0000266 ) -> Result<Parcel> {
Stephen Crane2a3c2502020-06-16 17:48:35 -0700267 let mut reply = ptr::null_mut();
268 let status = unsafe {
269 // Safety: `SpIBinder` guarantees that `self` always contains a
270 // valid pointer to an `AIBinder`. Although `IBinder::transact` is
271 // not a const method, it is still safe to cast our immutable
272 // pointer to mutable for the call. First, `IBinder::transact` is
273 // thread-safe, so concurrency is not an issue. The only way that
274 // `transact` can affect any visible, mutable state in the current
275 // process is by calling `onTransact` for a local service. However,
276 // in order for transactions to be thread-safe, this method must
277 // dynamically lock its data before modifying it. We enforce this
278 // property in Rust by requiring `Sync` for remotable objects and
279 // only providing `on_transact` with an immutable reference to
280 // `self`.
281 //
Alice Ryhlfeba6ca2021-08-19 10:47:04 +0000282 // This call takes ownership of the `data` parcel pointer, and
Stephen Crane2a3c2502020-06-16 17:48:35 -0700283 // passes ownership of the `reply` out parameter to its caller. It
284 // does not affect ownership of the `binder` parameter.
285 sys::AIBinder_transact(
286 self.as_native() as *mut sys::AIBinder,
287 code,
Alice Ryhlfeba6ca2021-08-19 10:47:04 +0000288 &mut data.into_raw(),
Stephen Crane2a3c2502020-06-16 17:48:35 -0700289 &mut reply,
290 flags,
291 )
292 };
293 status_result(status)?;
294
295 unsafe {
296 // Safety: `reply` is either a valid `AParcel` pointer or null
297 // after the call to `AIBinder_transact` above, so we can
298 // construct a `Parcel` out of it. `AIBinder_transact` passes
299 // ownership of the `reply` parcel to Rust, so we need to
Alice Ryhl268458c2021-09-15 12:56:10 +0000300 // construct an owned variant.
Alice Ryhl8618c482021-11-09 15:35:35 +0000301 Parcel::from_raw(reply).ok_or(StatusCode::UNEXPECTED_NULL)
Stephen Crane2a3c2502020-06-16 17:48:35 -0700302 }
303 }
304
305 fn is_binder_alive(&self) -> bool {
306 unsafe {
307 // Safety: `SpIBinder` guarantees that `self` always contains a
308 // valid pointer to an `AIBinder`.
309 //
310 // This call does not affect ownership of its pointer parameter.
311 sys::AIBinder_isAlive(self.as_native())
312 }
313 }
314
315 fn ping_binder(&mut self) -> Result<()> {
316 let status = unsafe {
317 // Safety: `SpIBinder` guarantees that `self` always contains a
318 // valid pointer to an `AIBinder`.
319 //
320 // This call does not affect ownership of its pointer parameter.
321 sys::AIBinder_ping(self.as_native_mut())
322 };
323 status_result(status)
324 }
325
Janis Danisevskis798a09a2020-08-18 08:35:38 -0700326 fn set_requesting_sid(&mut self, enable: bool) {
Andrew Walbran12400d82021-03-04 17:04:34 +0000327 unsafe { sys::AIBinder_setRequestingSid(self.as_native_mut(), enable) };
Janis Danisevskis798a09a2020-08-18 08:35:38 -0700328 }
329
Stephen Crane2a3c2502020-06-16 17:48:35 -0700330 fn dump<F: AsRawFd>(&mut self, fp: &F, args: &[&str]) -> Result<()> {
331 let args: Vec<_> = args.iter().map(|a| CString::new(*a).unwrap()).collect();
332 let mut arg_ptrs: Vec<_> = args.iter().map(|a| a.as_ptr()).collect();
333 let status = unsafe {
334 // Safety: `SpIBinder` guarantees that `self` always contains a
335 // valid pointer to an `AIBinder`. `AsRawFd` guarantees that the
336 // file descriptor parameter is always be a valid open file. The
337 // `args` pointer parameter is a valid pointer to an array of C
338 // strings that will outlive the call since `args` lives for the
339 // whole function scope.
340 //
341 // This call does not affect ownership of its binder pointer
342 // parameter and does not take ownership of the file or args array
343 // parameters.
344 sys::AIBinder_dump(
345 self.as_native_mut(),
346 fp.as_raw_fd(),
347 arg_ptrs.as_mut_ptr(),
348 arg_ptrs.len().try_into().unwrap(),
349 )
350 };
351 status_result(status)
352 }
353
354 fn get_extension(&mut self) -> Result<Option<SpIBinder>> {
355 let mut out = ptr::null_mut();
356 let status = unsafe {
357 // Safety: `SpIBinder` guarantees that `self` always contains a
358 // valid pointer to an `AIBinder`. After this call, the `out`
359 // parameter will be either null, or a valid pointer to an
360 // `AIBinder`.
361 //
362 // This call passes ownership of the out pointer to its caller
363 // (assuming it is set to a non-null value).
364 sys::AIBinder_getExtension(self.as_native_mut(), &mut out)
365 };
366 let ibinder = unsafe {
367 // Safety: The call above guarantees that `out` is either null or a
368 // valid, owned pointer to an `AIBinder`, both of which are safe to
369 // pass to `SpIBinder::from_raw`.
370 SpIBinder::from_raw(out)
371 };
372
373 status_result(status)?;
374 Ok(ibinder)
375 }
Andrew Walbran12400d82021-03-04 17:04:34 +0000376}
Stephen Crane2a3c2502020-06-16 17:48:35 -0700377
Andrew Walbran12400d82021-03-04 17:04:34 +0000378impl<T: AsNative<sys::AIBinder>> IBinder for T {
Stephen Crane2a3c2502020-06-16 17:48:35 -0700379 fn link_to_death(&mut self, recipient: &mut DeathRecipient) -> Result<()> {
380 status_result(unsafe {
381 // Safety: `SpIBinder` guarantees that `self` always contains a
382 // valid pointer to an `AIBinder`. `recipient` can always be
383 // converted into a valid pointer to an
Alice Ryhlea9d9d22021-08-27 07:51:30 +0000384 // `AIBinder_DeathRecipient`.
385 //
386 // The cookie is also the correct pointer, and by calling new_cookie,
387 // we have created a new ref-count to the cookie, which linkToDeath
388 // takes ownership of. Once the DeathRecipient is unlinked for any
389 // reason (including if this call fails), the onUnlinked callback
390 // will consume that ref-count.
Stephen Crane2a3c2502020-06-16 17:48:35 -0700391 sys::AIBinder_linkToDeath(
392 self.as_native_mut(),
393 recipient.as_native_mut(),
Alice Ryhlea9d9d22021-08-27 07:51:30 +0000394 recipient.new_cookie(),
Stephen Crane2a3c2502020-06-16 17:48:35 -0700395 )
396 })
397 }
398
399 fn unlink_to_death(&mut self, recipient: &mut DeathRecipient) -> Result<()> {
400 status_result(unsafe {
401 // Safety: `SpIBinder` guarantees that `self` always contains a
402 // valid pointer to an `AIBinder`. `recipient` can always be
403 // converted into a valid pointer to an
Stephen Craneddb3e6d2020-12-18 13:27:22 -0800404 // `AIBinder_DeathRecipient`. Any value is safe to pass as the
Stephen Crane2a3c2502020-06-16 17:48:35 -0700405 // cookie, although we depend on this value being set by
406 // `get_cookie` when the death recipient callback is called.
407 sys::AIBinder_unlinkToDeath(
408 self.as_native_mut(),
409 recipient.as_native_mut(),
410 recipient.get_cookie(),
411 )
412 })
413 }
414}
415
416impl Serialize for SpIBinder {
Alice Ryhl8618c482021-11-09 15:35:35 +0000417 fn serialize(&self, parcel: &mut BorrowedParcel<'_>) -> Result<()> {
Stephen Crane2a3c2502020-06-16 17:48:35 -0700418 parcel.write_binder(Some(self))
419 }
420}
421
422impl SerializeOption for SpIBinder {
Alice Ryhl8618c482021-11-09 15:35:35 +0000423 fn serialize_option(this: Option<&Self>, parcel: &mut BorrowedParcel<'_>) -> Result<()> {
Stephen Crane2a3c2502020-06-16 17:48:35 -0700424 parcel.write_binder(this)
425 }
426}
427
428impl SerializeArray for SpIBinder {}
Stephen Crane2a3c2502020-06-16 17:48:35 -0700429
430impl Deserialize for SpIBinder {
Alice Ryhl8618c482021-11-09 15:35:35 +0000431 fn deserialize(parcel: &BorrowedParcel<'_>) -> Result<SpIBinder> {
Andrei Homescu32814372020-08-20 15:36:08 -0700432 parcel
433 .read_binder()
434 .transpose()
435 .unwrap_or(Err(StatusCode::UNEXPECTED_NULL))
Stephen Crane2a3c2502020-06-16 17:48:35 -0700436 }
437}
438
439impl DeserializeOption for SpIBinder {
Alice Ryhl8618c482021-11-09 15:35:35 +0000440 fn deserialize_option(parcel: &BorrowedParcel<'_>) -> Result<Option<SpIBinder>> {
Stephen Crane2a3c2502020-06-16 17:48:35 -0700441 parcel.read_binder()
442 }
443}
444
445impl DeserializeArray for SpIBinder {}
Stephen Crane2a3c2502020-06-16 17:48:35 -0700446
447/// A weak reference to a Binder remote object.
448///
Andrew Walbran8fe3ecc2020-12-15 11:29:58 +0000449/// This struct encapsulates the generic C++ `wp<IBinder>` class. This wrapper
450/// is untyped; typed interface access is implemented by the AIDL compiler.
Alice Ryhl8dde9bc2021-08-16 16:57:10 +0000451pub struct WpIBinder(ptr::NonNull<sys::AIBinder_Weak>);
Stephen Crane2a3c2502020-06-16 17:48:35 -0700452
Andrew Walbran8fe3ecc2020-12-15 11:29:58 +0000453impl fmt::Debug for WpIBinder {
454 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
455 f.pad("WpIBinder")
456 }
457}
458
459/// # Safety
460///
Stephen Cranef03fe3d2021-06-25 15:05:00 -0700461/// A `WpIBinder` is an immutable handle to a C++ IBinder, which is thread-safe.
Andrew Walbran8fe3ecc2020-12-15 11:29:58 +0000462unsafe impl Send for WpIBinder {}
463
Stephen Cranef03fe3d2021-06-25 15:05:00 -0700464/// # Safety
465///
466/// A `WpIBinder` is an immutable handle to a C++ IBinder, which is thread-safe.
467unsafe impl Sync for WpIBinder {}
468
Stephen Crane2a3c2502020-06-16 17:48:35 -0700469impl WpIBinder {
470 /// Create a new weak reference from an object that can be converted into a
471 /// raw `AIBinder` pointer.
Andrew Walbran8fe3ecc2020-12-15 11:29:58 +0000472 fn new<B: AsNative<sys::AIBinder>>(binder: &mut B) -> WpIBinder {
Stephen Crane2a3c2502020-06-16 17:48:35 -0700473 let ptr = unsafe {
474 // Safety: `SpIBinder` guarantees that `binder` always contains a
475 // valid pointer to an `AIBinder`.
476 sys::AIBinder_Weak_new(binder.as_native_mut())
477 };
Alice Ryhl8dde9bc2021-08-16 16:57:10 +0000478 Self(ptr::NonNull::new(ptr).expect("Unexpected null pointer from AIBinder_Weak_new"))
Stephen Crane2a3c2502020-06-16 17:48:35 -0700479 }
Stephen Crane994a0f02020-08-11 14:47:29 -0700480
481 /// Promote this weak reference to a strong reference to the binder object.
482 pub fn promote(&self) -> Option<SpIBinder> {
483 unsafe {
484 // Safety: `WpIBinder` always contains a valid weak reference, so we
485 // can pass this pointer to `AIBinder_Weak_promote`. Returns either
486 // null or an AIBinder owned by the caller, both of which are valid
487 // to pass to `SpIBinder::from_raw`.
Alice Ryhl8dde9bc2021-08-16 16:57:10 +0000488 let ptr = sys::AIBinder_Weak_promote(self.0.as_ptr());
Stephen Crane994a0f02020-08-11 14:47:29 -0700489 SpIBinder::from_raw(ptr)
490 }
491 }
Stephen Crane2a3c2502020-06-16 17:48:35 -0700492}
493
Stephen Craneddb3e6d2020-12-18 13:27:22 -0800494impl Clone for WpIBinder {
495 fn clone(&self) -> Self {
496 let ptr = unsafe {
497 // Safety: WpIBinder always holds a valid `AIBinder_Weak` pointer,
498 // so this pointer is always safe to pass to `AIBinder_Weak_clone`
499 // (although null is also a safe value to pass to this API).
500 //
501 // We get ownership of the returned pointer, so can construct a new
502 // WpIBinder object from it.
Alice Ryhl8dde9bc2021-08-16 16:57:10 +0000503 sys::AIBinder_Weak_clone(self.0.as_ptr())
Stephen Craneddb3e6d2020-12-18 13:27:22 -0800504 };
Alice Ryhl8dde9bc2021-08-16 16:57:10 +0000505 Self(ptr::NonNull::new(ptr).expect("Unexpected null pointer from AIBinder_Weak_clone"))
Stephen Craneddb3e6d2020-12-18 13:27:22 -0800506 }
507}
508
509impl Ord for WpIBinder {
510 fn cmp(&self, other: &Self) -> Ordering {
511 let less_than = unsafe {
512 // Safety: WpIBinder always holds a valid `AIBinder_Weak` pointer,
513 // so this pointer is always safe to pass to `AIBinder_Weak_lt`
514 // (null is also safe to pass to this function, but we should never
515 // do that).
Alice Ryhl8dde9bc2021-08-16 16:57:10 +0000516 sys::AIBinder_Weak_lt(self.0.as_ptr(), other.0.as_ptr())
Stephen Craneddb3e6d2020-12-18 13:27:22 -0800517 };
518 let greater_than = unsafe {
519 // Safety: WpIBinder always holds a valid `AIBinder_Weak` pointer,
520 // so this pointer is always safe to pass to `AIBinder_Weak_lt`
521 // (null is also safe to pass to this function, but we should never
522 // do that).
Alice Ryhl8dde9bc2021-08-16 16:57:10 +0000523 sys::AIBinder_Weak_lt(other.0.as_ptr(), self.0.as_ptr())
Stephen Craneddb3e6d2020-12-18 13:27:22 -0800524 };
525 if !less_than && !greater_than {
526 Ordering::Equal
527 } else if less_than {
528 Ordering::Less
529 } else {
530 Ordering::Greater
531 }
532 }
533}
534
535impl PartialOrd for WpIBinder {
536 fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
537 Some(self.cmp(other))
538 }
539}
540
541impl PartialEq for WpIBinder {
542 fn eq(&self, other: &Self) -> bool {
543 self.cmp(other) == Ordering::Equal
544 }
545}
546
547impl Eq for WpIBinder {}
548
Andrew Walbran5e8dfa32020-12-16 12:50:06 +0000549impl Drop for WpIBinder {
550 fn drop(&mut self) {
551 unsafe {
552 // Safety: WpIBinder always holds a valid `AIBinder_Weak` pointer, so we
553 // know this pointer is safe to pass to `AIBinder_Weak_delete` here.
Alice Ryhl8dde9bc2021-08-16 16:57:10 +0000554 sys::AIBinder_Weak_delete(self.0.as_ptr());
Andrew Walbran5e8dfa32020-12-16 12:50:06 +0000555 }
556 }
557}
558
Stephen Crane2a3c2502020-06-16 17:48:35 -0700559/// Rust wrapper around DeathRecipient objects.
Alice Ryhlea9d9d22021-08-27 07:51:30 +0000560///
561/// The cookie in this struct represents an Arc<F> for the owned callback.
562/// This struct owns a ref-count of it, and so does every binder that we
563/// have been linked with.
Stephen Crane2a3c2502020-06-16 17:48:35 -0700564#[repr(C)]
565pub struct DeathRecipient {
566 recipient: *mut sys::AIBinder_DeathRecipient,
Alice Ryhlea9d9d22021-08-27 07:51:30 +0000567 cookie: *mut c_void,
568 vtable: &'static DeathRecipientVtable,
569}
570
571struct DeathRecipientVtable {
572 cookie_incr_refcount: unsafe extern "C" fn(*mut c_void),
573 cookie_decr_refcount: unsafe extern "C" fn(*mut c_void),
Stephen Crane2a3c2502020-06-16 17:48:35 -0700574}
575
576impl DeathRecipient {
577 /// Create a new death recipient that will call the given callback when its
578 /// associated object dies.
579 pub fn new<F>(callback: F) -> DeathRecipient
580 where
Alice Ryhlea9d9d22021-08-27 07:51:30 +0000581 F: Fn() + Send + Sync + 'static,
Stephen Crane2a3c2502020-06-16 17:48:35 -0700582 {
Alice Ryhlea9d9d22021-08-27 07:51:30 +0000583 let callback: *const F = Arc::into_raw(Arc::new(callback));
Stephen Crane2a3c2502020-06-16 17:48:35 -0700584 let recipient = unsafe {
585 // Safety: The function pointer is a valid death recipient callback.
586 //
587 // This call returns an owned `AIBinder_DeathRecipient` pointer
588 // which must be destroyed via `AIBinder_DeathRecipient_delete` when
589 // no longer needed.
590 sys::AIBinder_DeathRecipient_new(Some(Self::binder_died::<F>))
591 };
Alice Ryhlea9d9d22021-08-27 07:51:30 +0000592 unsafe {
593 // Safety: The function pointer is a valid onUnlinked callback.
594 //
595 // All uses of linkToDeath in this file correctly increment the
596 // ref-count that this onUnlinked callback will decrement.
597 sys::AIBinder_DeathRecipient_setOnUnlinked(recipient, Some(Self::cookie_decr_refcount::<F>));
598 }
Stephen Crane2a3c2502020-06-16 17:48:35 -0700599 DeathRecipient {
600 recipient,
Alice Ryhlea9d9d22021-08-27 07:51:30 +0000601 cookie: callback as *mut c_void,
602 vtable: &DeathRecipientVtable {
603 cookie_incr_refcount: Self::cookie_incr_refcount::<F>,
604 cookie_decr_refcount: Self::cookie_decr_refcount::<F>,
605 },
Stephen Crane2a3c2502020-06-16 17:48:35 -0700606 }
607 }
608
Alice Ryhlea9d9d22021-08-27 07:51:30 +0000609 /// Increment the ref-count for the cookie and return it.
610 ///
611 /// # Safety
612 ///
613 /// The caller must handle the returned ref-count correctly.
614 unsafe fn new_cookie(&self) -> *mut c_void {
615 (self.vtable.cookie_incr_refcount)(self.cookie);
616
617 // Return a raw pointer with ownership of a ref-count
618 self.cookie
619 }
620
Stephen Crane2a3c2502020-06-16 17:48:35 -0700621 /// Get the opaque cookie that identifies this death recipient.
622 ///
623 /// This cookie will be used to link and unlink this death recipient to a
624 /// binder object and will be passed to the `binder_died` callback as an
625 /// opaque userdata pointer.
626 fn get_cookie(&self) -> *mut c_void {
Alice Ryhlea9d9d22021-08-27 07:51:30 +0000627 self.cookie
Stephen Crane2a3c2502020-06-16 17:48:35 -0700628 }
629
630 /// Callback invoked from C++ when the binder object dies.
631 ///
632 /// # Safety
633 ///
Alice Ryhlea9d9d22021-08-27 07:51:30 +0000634 /// The `cookie` parameter must be the cookie for an Arc<F> and
635 /// the caller must hold a ref-count to it.
Stephen Crane2a3c2502020-06-16 17:48:35 -0700636 unsafe extern "C" fn binder_died<F>(cookie: *mut c_void)
637 where
Alice Ryhlea9d9d22021-08-27 07:51:30 +0000638 F: Fn() + Send + Sync + 'static,
Stephen Crane2a3c2502020-06-16 17:48:35 -0700639 {
Alice Ryhlea9d9d22021-08-27 07:51:30 +0000640 let callback = (cookie as *const F).as_ref().unwrap();
Stephen Crane2a3c2502020-06-16 17:48:35 -0700641 callback();
642 }
Alice Ryhlea9d9d22021-08-27 07:51:30 +0000643
644 /// Callback that decrements the ref-count.
645 /// This is invoked from C++ when a binder is unlinked.
646 ///
647 /// # Safety
648 ///
649 /// The `cookie` parameter must be the cookie for an Arc<F> and
650 /// the owner must give up a ref-count to it.
651 unsafe extern "C" fn cookie_decr_refcount<F>(cookie: *mut c_void)
652 where
653 F: Fn() + Send + Sync + 'static,
654 {
655 drop(Arc::from_raw(cookie as *const F));
656 }
657
658 /// Callback that increments the ref-count.
659 ///
660 /// # Safety
661 ///
662 /// The `cookie` parameter must be the cookie for an Arc<F> and
663 /// the owner must handle the created ref-count properly.
664 unsafe extern "C" fn cookie_incr_refcount<F>(cookie: *mut c_void)
665 where
666 F: Fn() + Send + Sync + 'static,
667 {
668 let arc = mem::ManuallyDrop::new(Arc::from_raw(cookie as *const F));
669 mem::forget(Arc::clone(&arc));
670 }
Stephen Crane2a3c2502020-06-16 17:48:35 -0700671}
672
673/// # Safety
674///
675/// A `DeathRecipient` is always constructed with a valid raw pointer to an
676/// `AIBinder_DeathRecipient`, so it is always type-safe to extract this
677/// pointer.
678unsafe impl AsNative<sys::AIBinder_DeathRecipient> for DeathRecipient {
679 fn as_native(&self) -> *const sys::AIBinder_DeathRecipient {
680 self.recipient
681 }
682
683 fn as_native_mut(&mut self) -> *mut sys::AIBinder_DeathRecipient {
684 self.recipient
685 }
686}
687
688impl Drop for DeathRecipient {
689 fn drop(&mut self) {
690 unsafe {
691 // Safety: `self.recipient` is always a valid, owned
692 // `AIBinder_DeathRecipient` pointer returned by
693 // `AIBinder_DeathRecipient_new` when `self` was created. This
694 // delete method can only be called once when `self` is dropped.
695 sys::AIBinder_DeathRecipient_delete(self.recipient);
Alice Ryhlea9d9d22021-08-27 07:51:30 +0000696
697 // Safety: We own a ref-count to the cookie, and so does every
698 // linked binder. This call gives up our ref-count. The linked
699 // binders should already have given up their ref-count, or should
700 // do so shortly.
701 (self.vtable.cookie_decr_refcount)(self.cookie)
Stephen Crane2a3c2502020-06-16 17:48:35 -0700702 }
703 }
704}
705
706/// Generic interface to remote binder objects.
707///
708/// Corresponds to the C++ `BpInterface` class.
709pub trait Proxy: Sized + Interface {
710 /// The Binder interface descriptor string.
711 ///
712 /// This string is a unique identifier for a Binder interface, and should be
713 /// the same between all implementations of that interface.
714 fn get_descriptor() -> &'static str;
715
716 /// Create a new interface from the given proxy, if it matches the expected
717 /// type of this interface.
718 fn from_binder(binder: SpIBinder) -> Result<Self>;
719}
720
721/// # Safety
722///
723/// This is a convenience method that wraps `AsNative` for `SpIBinder` to allow
724/// invocation of `IBinder` methods directly from `Interface` objects. It shares
725/// the same safety as the implementation for `SpIBinder`.
726unsafe impl<T: Proxy> AsNative<sys::AIBinder> for T {
727 fn as_native(&self) -> *const sys::AIBinder {
728 self.as_binder().as_native()
729 }
730
731 fn as_native_mut(&mut self) -> *mut sys::AIBinder {
732 self.as_binder().as_native_mut()
733 }
734}
735
736/// Retrieve an existing service, blocking for a few seconds if it doesn't yet
737/// exist.
738pub fn get_service(name: &str) -> Option<SpIBinder> {
739 let name = CString::new(name).ok()?;
740 unsafe {
741 // Safety: `AServiceManager_getService` returns either a null pointer or
742 // a valid pointer to an owned `AIBinder`. Either of these values is
743 // safe to pass to `SpIBinder::from_raw`.
744 SpIBinder::from_raw(sys::AServiceManager_getService(name.as_ptr()))
745 }
746}
747
Andrew Walbranc3ce5c32021-06-03 16:15:56 +0000748/// Retrieve an existing service, or start it if it is configured as a dynamic
749/// service and isn't yet started.
750pub fn wait_for_service(name: &str) -> Option<SpIBinder> {
751 let name = CString::new(name).ok()?;
752 unsafe {
753 // Safety: `AServiceManager_waitforService` returns either a null
754 // pointer or a valid pointer to an owned `AIBinder`. Either of these
755 // values is safe to pass to `SpIBinder::from_raw`.
756 SpIBinder::from_raw(sys::AServiceManager_waitForService(name.as_ptr()))
757 }
758}
759
Stephen Crane2a3c2502020-06-16 17:48:35 -0700760/// Retrieve an existing service for a particular interface, blocking for a few
761/// seconds if it doesn't yet exist.
Stephen Craneddb3e6d2020-12-18 13:27:22 -0800762pub fn get_interface<T: FromIBinder + ?Sized>(name: &str) -> Result<Strong<T>> {
Stephen Crane2a3c2502020-06-16 17:48:35 -0700763 let service = get_service(name);
764 match service {
765 Some(service) => FromIBinder::try_from(service),
766 None => Err(StatusCode::NAME_NOT_FOUND),
767 }
768}
769
Andrew Walbranc3ce5c32021-06-03 16:15:56 +0000770/// Retrieve an existing service for a particular interface, or start it if it
771/// is configured as a dynamic service and isn't yet started.
772pub fn wait_for_interface<T: FromIBinder + ?Sized>(name: &str) -> Result<Strong<T>> {
773 let service = wait_for_service(name);
774 match service {
775 Some(service) => FromIBinder::try_from(service),
776 None => Err(StatusCode::NAME_NOT_FOUND),
777 }
778}
779
Stephen Crane2a3c2502020-06-16 17:48:35 -0700780/// # Safety
781///
782/// `SpIBinder` guarantees that `binder` always contains a valid pointer to an
783/// `AIBinder`, so we can trivially extract this pointer here.
784unsafe impl AsNative<sys::AIBinder> for SpIBinder {
785 fn as_native(&self) -> *const sys::AIBinder {
Alice Ryhl8dde9bc2021-08-16 16:57:10 +0000786 self.0.as_ptr()
Stephen Crane2a3c2502020-06-16 17:48:35 -0700787 }
788
789 fn as_native_mut(&mut self) -> *mut sys::AIBinder {
Alice Ryhl8dde9bc2021-08-16 16:57:10 +0000790 self.0.as_ptr()
Stephen Crane2a3c2502020-06-16 17:48:35 -0700791 }
792}