• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (C) 2018 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 /**
18  * @addtogroup NdkBinder
19  * @{
20  */
21 
22 /**
23  * @file binder_ibinder.h
24  * @brief Object which can receive transactions and be sent across processes.
25  */
26 
27 #pragma once
28 
29 #include <stdbool.h>
30 #include <stdint.h>
31 #include <sys/cdefs.h>
32 #include <sys/types.h>
33 
34 #include <android/binder_parcel.h>
35 #include <android/binder_status.h>
36 
37 __BEGIN_DECLS
38 
39 /**
40  * Flags for AIBinder_transact.
41  */
42 typedef uint32_t binder_flags_t;
43 enum {
44     /**
45      * The transaction will be dispatched and then returned to the caller. The outgoing process
46      * cannot block a call made by this, and execution of the call will not be waited on. An error
47      * can still be returned if the call is unable to be processed by the binder driver. All oneway
48      * calls are guaranteed to be ordered if they are sent on the same AIBinder object.
49      */
50     FLAG_ONEWAY = 0x01,
51 };
52 
53 /**
54  * Codes for AIBinder_transact. This defines the range of codes available for
55  * usage. Other codes are used or reserved by the Android system.
56  */
57 typedef uint32_t transaction_code_t;
58 enum {
59     /**
60      * The first transaction code available for user commands (inclusive).
61      */
62     FIRST_CALL_TRANSACTION = 0x00000001,
63     /**
64      * The last transaction code available for user commands (inclusive).
65      */
66     LAST_CALL_TRANSACTION = 0x00ffffff,
67 };
68 
69 /**
70  * Represents a type of AIBinder object which can be sent out.
71  */
72 struct AIBinder_Class;
73 typedef struct AIBinder_Class AIBinder_Class;
74 
75 /**
76  * Represents a local or remote object which can be used for IPC or which can itself be sent.
77  *
78  * This object has a refcount associated with it and will be deleted when its refcount reaches zero.
79  * How methods interactive with this refcount is described below. When using this API, it is
80  * intended for a client of a service to hold a strong reference to that service. This also means
81  * that user data typically should hold a strong reference to a local AIBinder object. A remote
82  * AIBinder object automatically holds a strong reference to the AIBinder object in the server's
83  * process. A typically memory layout looks like this:
84  *
85  * Key:
86  *   --->         Ownership/a strong reference
87  *   ...>         A weak reference
88  *
89  *                         (process boundary)
90  *                                 |
91  * MyInterface ---> AIBinder_Weak  |  ProxyForMyInterface
92  *      ^                .         |          |
93  *      |                .         |          |
94  *      |                v         |          v
95  *   UserData  <---   AIBinder   <-|-      AIBinder
96  *                                 |
97  *
98  * In this way, you'll notice that a proxy for the interface holds a strong reference to the
99  * implementation and that in the server process, the AIBinder object which was sent can be resent
100  * so that the same AIBinder object always represents the same object. This allows, for instance, an
101  * implementation (usually a callback) to transfer all ownership to a remote process and
102  * automatically be deleted when the remote process is done with it or dies. Other memory models are
103  * possible, but this is the standard one.
104  *
105  * If the process containing an AIBinder dies, it is possible to be holding a strong reference to
106  * an object which does not exist. In this case, transactions to this binder will return
107  * STATUS_DEAD_OBJECT. See also AIBinder_linkToDeath, AIBinder_unlinkToDeath, and AIBinder_isAlive.
108  *
109  * Once an AIBinder is created, anywhere it is passed (remotely or locally), there is a 1-1
110  * correspondence between the address of an AIBinder and the object it represents. This means that
111  * when two AIBinder pointers point to the same address, they represent the same object (whether
112  * that object is local or remote). This correspondance can be broken accidentally if AIBinder_new
113  * is erronesouly called to create the same object multiple times.
114  */
115 struct AIBinder;
116 typedef struct AIBinder AIBinder;
117 
118 /**
119  * The AIBinder object associated with this can be retrieved if it is still alive so that it can be
120  * re-used. The intention of this is to enable the same AIBinder object to always represent the same
121  * object.
122  */
123 struct AIBinder_Weak;
124 typedef struct AIBinder_Weak AIBinder_Weak;
125 
126 /**
127  * Represents a handle on a death notification. See AIBinder_linkToDeath/AIBinder_unlinkToDeath.
128  */
129 struct AIBinder_DeathRecipient;
130 typedef struct AIBinder_DeathRecipient AIBinder_DeathRecipient;
131 
132 /**
133  * This is called whenever a new AIBinder object is needed of a specific class.
134  *
135  * \param args these can be used to construct a new class. These are passed from AIBinder_new.
136  * \return this is the userdata representing the class. It can be retrieved using
137  * AIBinder_getUserData.
138  */
139 typedef void* (*AIBinder_Class_onCreate)(void* args);
140 
141 /**
142  * This is called whenever an AIBinder object is no longer referenced and needs destroyed.
143  *
144  * Typically, this just deletes whatever the implementation is.
145  *
146  * \param userData this is the same object returned by AIBinder_Class_onCreate
147  */
148 typedef void (*AIBinder_Class_onDestroy)(void* userData);
149 
150 /**
151  * This is called whenever a transaction needs to be processed by a local implementation.
152  *
153  * This method will be called after the equivalent of
154  * android.os.Parcel#enforceInterface is called. That is, the interface
155  * descriptor associated with the AIBinder_Class descriptor will already be
156  * checked.
157  *
158  * \param binder the object being transacted on.
159  * \param code implementation-specific code representing which transaction should be taken.
160  * \param in the implementation-specific input data to this transaction.
161  * \param out the implementation-specific output data to this transaction.
162  *
163  * \return the implementation-specific output code. This may be forwarded from another service, the
164  * result of a parcel read or write, or another error as is applicable to the specific
165  * implementation. Usually, implementation-specific error codes are written to the output parcel,
166  * and the transaction code is reserved for kernel errors or error codes that have been repeated
167  * from subsequent transactions.
168  */
169 typedef binder_status_t (*AIBinder_Class_onTransact)(AIBinder* binder, transaction_code_t code,
170                                                      const AParcel* in, AParcel* out);
171 
172 /**
173  * This creates a new instance of a class of binders which can be instantiated. This is called one
174  * time during library initialization and cleaned up when the process exits or execs.
175  *
176  * None of these parameters can be null.
177  *
178  * Available since API level 29.
179  *
180  * \param interfaceDescriptor this is a unique identifier for the class. This is used internally for
181  * validity checks on transactions. This should be utf-8.
182  * \param onCreate see AIBinder_Class_onCreate.
183  * \param onDestroy see AIBinder_Class_onDestroy.
184  * \param onTransact see AIBinder_Class_onTransact.
185  *
186  * \return the class object representing these parameters or null on error.
187  */
188 __attribute__((warn_unused_result)) AIBinder_Class* AIBinder_Class_define(
189         const char* interfaceDescriptor, AIBinder_Class_onCreate onCreate,
190         AIBinder_Class_onDestroy onDestroy, AIBinder_Class_onTransact onTransact)
191         __INTRODUCED_IN(29);
192 
193 /**
194  * Dump information about an AIBinder (usually for debugging).
195  *
196  * When no arguments are provided, a brief overview of the interview should be given.
197  *
198  * \param binder interface being dumped
199  * \param fd file descriptor to be dumped to, should be flushed, ownership is not passed.
200  * \param args array of null-terminated strings for dump (may be null if numArgs is 0)
201  * \param numArgs number of args to be sent
202  *
203  * \return binder_status_t result of transaction (if remote, for instance)
204  */
205 typedef binder_status_t (*AIBinder_onDump)(AIBinder* binder, int fd, const char** args,
206                                            uint32_t numArgs);
207 
208 /**
209  * This sets the implementation of the dump method for a class.
210  *
211  * If this isn't set, nothing will be dumped when dump is called (for instance with
212  * android.os.Binder#dump). Must be called before any instance of the class is created.
213  *
214  * Available since API level 29.
215  *
216  * \param clazz class which should use this dump function
217  * \param onDump function to call when an instance of this binder class is being dumped.
218  */
219 void AIBinder_Class_setOnDump(AIBinder_Class* clazz, AIBinder_onDump onDump) __INTRODUCED_IN(29);
220 
221 /**
222  * This tells users of this class not to use a transaction header. By default, libbinder_ndk users
223  * read/write transaction headers implicitly (in the SDK, this must be manually written by
224  * android.os.Parcel#writeInterfaceToken, and it is read/checked with
225  * android.os.Parcel#enforceInterface). This method is provided in order to talk to legacy code
226  * which does not write an interface token. When this is disabled, type safety is reduced, so you
227  * must have a separate way of determining the binder you are talking to is the right type. Must
228  * be called before any instance of the class is created.
229  *
230  * Available since API level 33.
231  *
232  * \param clazz class to disable interface header on.
233  */
234 void AIBinder_Class_disableInterfaceTokenHeader(AIBinder_Class* clazz) __INTRODUCED_IN(33);
235 
236 /**
237  * Creates a new binder object of the appropriate class.
238  *
239  * Ownership of args is passed to this object. The lifecycle is implemented with AIBinder_incStrong
240  * and AIBinder_decStrong. When the reference count reaches zero, onDestroy is called.
241  *
242  * When this is called, the refcount is implicitly 1. So, calling decStrong exactly one time is
243  * required to delete this object.
244  *
245  * Once an AIBinder object is created using this API, re-creating that AIBinder for the same
246  * instance of the same class will break pointer equality for that specific AIBinder object. For
247  * instance, if someone erroneously created two AIBinder instances representing the same callback
248  * object and passed one to a hypothetical addCallback function and then later another one to a
249  * hypothetical removeCallback function, the remote process would have no way to determine that
250  * these two objects are actually equal using the AIBinder pointer alone (which they should be able
251  * to do). Also see the suggested memory ownership model suggested above.
252  *
253  * Available since API level 29.
254  *
255  * \param clazz the type of the object to be created.
256  * \param args the args to pass to AIBinder_onCreate for that class.
257  *
258  * \return a binder object representing the newly instantiated object.
259  */
260 __attribute__((warn_unused_result)) AIBinder* AIBinder_new(const AIBinder_Class* clazz, void* args)
261         __INTRODUCED_IN(29);
262 
263 /**
264  * If this is hosted in a process other than the current one.
265  *
266  * Available since API level 29.
267  *
268  * \param binder the binder being queried.
269  *
270  * \return true if the AIBinder represents an object in another process.
271  */
272 bool AIBinder_isRemote(const AIBinder* binder) __INTRODUCED_IN(29);
273 
274 /**
275  * If this binder is known to be alive. This will not send a transaction to a remote process and
276  * returns a result based on the last known information. That is, whenever a transaction is made,
277  * this is automatically updated to reflect the current alive status of this binder. This will be
278  * updated as the result of a transaction made using AIBinder_transact, but it will also be updated
279  * based on the results of bookkeeping or other transactions made internally.
280  *
281  * Available since API level 29.
282  *
283  * \param binder the binder being queried.
284  *
285  * \return true if the binder is alive.
286  */
287 bool AIBinder_isAlive(const AIBinder* binder) __INTRODUCED_IN(29);
288 
289 /**
290  * Built-in transaction for all binder objects. This sends a transaction that will immediately
291  * return. Usually this is used to make sure that a binder is alive, as a placeholder call, or as a
292  * consistency check.
293  *
294  * Available since API level 29.
295  *
296  * \param binder the binder being queried.
297  *
298  * \return STATUS_OK if the ping succeeds.
299  */
300 binder_status_t AIBinder_ping(AIBinder* binder) __INTRODUCED_IN(29);
301 
302 /**
303  * Built-in transaction for all binder objects. This dumps information about a given binder.
304  *
305  * See also AIBinder_Class_setOnDump, AIBinder_onDump.
306  *
307  * Available since API level 29.
308  *
309  * \param binder the binder to dump information about
310  * \param fd where information should be dumped to
311  * \param args null-terminated arguments to pass (may be null if numArgs is 0)
312  * \param numArgs number of args to send
313  *
314  * \return STATUS_OK if dump succeeds (or if there is nothing to dump)
315  */
316 binder_status_t AIBinder_dump(AIBinder* binder, int fd, const char** args, uint32_t numArgs)
317         __INTRODUCED_IN(29);
318 
319 /**
320  * Registers for notifications that the associated binder is dead. The same death recipient may be
321  * associated with multiple different binders. If the binder is local, then no death recipient will
322  * be given (since if the local process dies, then no recipient will exist to receive a
323  * transaction). The cookie is passed to recipient in the case that this binder dies and can be
324  * null. The exact cookie must also be used to unlink this transaction (see AIBinder_unlinkToDeath).
325  * This function may return a binder transaction failure. The cookie can be used both for
326  * identification and holding user data.
327  *
328  * If binder is local, this will return STATUS_INVALID_OPERATION.
329  *
330  * Available since API level 29.
331  *
332  * \param binder the binder object you want to receive death notifications from.
333  * \param recipient the callback that will receive notifications when/if the binder dies.
334  * \param cookie the value that will be passed to the death recipient on death.
335  *
336  * \return STATUS_OK on success.
337  */
338 binder_status_t AIBinder_linkToDeath(AIBinder* binder, AIBinder_DeathRecipient* recipient,
339                                      void* cookie) __INTRODUCED_IN(29);
340 
341 /**
342  * Stops registration for the associated binder dying. Does not delete the recipient. This function
343  * may return a binder transaction failure and in case the death recipient cannot be found, it
344  * returns STATUS_NAME_NOT_FOUND.
345  *
346  * This only ever needs to be called when the AIBinder_DeathRecipient remains for use with other
347  * AIBinder objects. If the death recipient is deleted, all binders will automatically be unlinked.
348  * If the binder dies, it will automatically unlink. If the binder is deleted, it will be
349  * automatically unlinked.
350  *
351  * Be aware that it is not safe to immediately deallocate the cookie when this call returns. If you
352  * need to clean up the cookie, you should do so in the onUnlinked callback, which can be set using
353  * AIBinder_DeathRecipient_setOnUnlinked.
354  *
355  * Available since API level 29.
356  *
357  * \param binder the binder object to remove a previously linked death recipient from.
358  * \param recipient the callback to remove.
359  * \param cookie the cookie used to link to death.
360  *
361  * \return STATUS_OK on success. STATUS_NAME_NOT_FOUND if the binder cannot be found to be unlinked.
362  */
363 binder_status_t AIBinder_unlinkToDeath(AIBinder* binder, AIBinder_DeathRecipient* recipient,
364                                        void* cookie) __INTRODUCED_IN(29);
365 
366 /**
367  * This returns the calling UID assuming that this thread is called from a thread that is processing
368  * a binder transaction (for instance, in the implementation of AIBinder_Class_onTransact).
369  *
370  * This can be used with higher-level system services to determine the caller's identity and check
371  * permissions.
372  *
373  * Available since API level 29.
374  *
375  * \return calling uid or the current process's UID if this thread isn't processing a transaction.
376  */
377 uid_t AIBinder_getCallingUid() __INTRODUCED_IN(29);
378 
379 /**
380  * This returns the calling PID assuming that this thread is called from a thread that is processing
381  * a binder transaction (for instance, in the implementation of AIBinder_Class_onTransact).
382  *
383  * This can be used with higher-level system services to determine the caller's identity and check
384  * permissions. However, when doing this, one should be aware of possible TOCTOU problems when the
385  * calling process dies and is replaced with another process with elevated permissions and the same
386  * PID.
387  *
388  * Available since API level 29.
389  *
390  * \return calling pid or the current process's PID if this thread isn't processing a transaction.
391  * If the transaction being processed is a oneway transaction, then this method will return 0.
392  */
393 pid_t AIBinder_getCallingPid() __INTRODUCED_IN(29);
394 
395 /**
396  * Determine whether the current thread is currently executing an incoming transaction.
397  *
398  * \return true if the current thread is currently executing an incoming transaction, and false
399  * otherwise.
400  */
401 bool AIBinder_isHandlingTransaction() __INTRODUCED_IN(33);
402 
403 /**
404  * This can only be called if a strong reference to this object already exists in process.
405  *
406  * Available since API level 29.
407  *
408  * \param binder the binder object to add a refcount to.
409  */
410 void AIBinder_incStrong(AIBinder* binder) __INTRODUCED_IN(29);
411 
412 /**
413  * This will delete the object and call onDestroy once the refcount reaches zero.
414  *
415  * Available since API level 29.
416  *
417  * \param binder the binder object to remove a refcount from.
418  */
419 void AIBinder_decStrong(AIBinder* binder) __INTRODUCED_IN(29);
420 
421 /**
422  * For debugging only!
423  *
424  * Available since API level 29.
425  *
426  * \param binder the binder object to retrieve the refcount of.
427  *
428  * \return the number of strong-refs on this binder in this process. If binder is null, this will be
429  * -1.
430  */
431 int32_t AIBinder_debugGetRefCount(AIBinder* binder) __INTRODUCED_IN(29);
432 
433 /**
434  * This sets the class of an AIBinder object. This checks to make sure the remote object is of
435  * the expected class. A class must be set in order to use transactions on an AIBinder object.
436  * However, if an object is just intended to be passed through to another process or used as a
437  * handle this need not be called.
438  *
439  * This returns true if the class association succeeds. If it fails, no change is made to the
440  * binder object.
441  *
442  * Warning: this may fail if the binder is dead.
443  *
444  * Available since API level 29.
445  *
446  * \param binder the object to attach the class to.
447  * \param clazz the clazz to attach to binder.
448  *
449  * \return true if the binder has the class clazz and if the association was successful.
450  */
451 bool AIBinder_associateClass(AIBinder* binder, const AIBinder_Class* clazz) __INTRODUCED_IN(29);
452 
453 /**
454  * Returns the class that this binder was constructed with or associated with.
455  *
456  * Available since API level 29.
457  *
458  * \param binder the object that is being queried.
459  *
460  * \return the class that this binder is associated with. If this binder wasn't created with
461  * AIBinder_new, and AIBinder_associateClass hasn't been called, then this will return null.
462  */
463 const AIBinder_Class* AIBinder_getClass(AIBinder* binder) __INTRODUCED_IN(29);
464 
465 /**
466  * Value returned by onCreate for a local binder. For stateless classes (if onCreate returns
467  * null), this also returns null. For a remote binder, this will always return null.
468  *
469  * Available since API level 29.
470  *
471  * \param binder the object that is being queried.
472  *
473  * \return the userdata returned from AIBinder_onCreate when this object was created. This may be
474  * null for stateless objects. For remote objects, this is always null.
475  */
476 void* AIBinder_getUserData(AIBinder* binder) __INTRODUCED_IN(29);
477 
478 /**
479  * A transaction is a series of calls to these functions which looks this
480  * - call AIBinder_prepareTransaction
481  * - fill out the in parcel with parameters (lifetime of the 'in' variable)
482  * - call AIBinder_transact
483  * - read results from the out parcel (lifetime of the 'out' variable)
484  */
485 
486 /**
487  * Creates a parcel to start filling out for a transaction. This will add a header to the
488  * transaction that corresponds to android.os.Parcel#writeInterfaceToken. This may add debugging
489  * or other information to the transaction for platform use or to enable other features to work. The
490  * contents of this header is a platform implementation detail, and it is required to use
491  * libbinder_ndk. This parcel is to be sent via AIBinder_transact and it represents the input data
492  * to the transaction. It is recommended to check if the object is local and call directly into its
493  * user data before calling this as the parceling and unparceling cost can be avoided. This AIBinder
494  * must be either built with a class or associated with a class before using this API.
495  *
496  * This does not affect the ownership of binder. When this function succeeds, the in parcel's
497  * ownership is passed to the caller. At this point, the parcel can be filled out and passed to
498  * AIBinder_transact. Alternatively, if there is an error while filling out the parcel, it can be
499  * deleted with AParcel_delete.
500  *
501  * Available since API level 29.
502  *
503  * \param binder the binder object to start a transaction on.
504  * \param in out parameter for input data to the transaction.
505  *
506  * \return STATUS_OK on success. This will return STATUS_INVALID_OPERATION if the binder has not yet
507  * been associated with a class (see AIBinder_new and AIBinder_associateClass).
508  */
509 binder_status_t AIBinder_prepareTransaction(AIBinder* binder, AParcel** in) __INTRODUCED_IN(29);
510 
511 /**
512  * Transact using a parcel created from AIBinder_prepareTransaction. This actually communicates with
513  * the object representing this binder object. This also passes out a parcel to be used for the
514  * return transaction. This takes ownership of the in parcel and automatically deletes it after it
515  * is sent to the remote process. The output parcel is the result of the transaction. If the
516  * transaction has FLAG_ONEWAY, the out parcel will be empty. Otherwise, this will block until the
517  * remote process has processed the transaction, and the out parcel will contain the output data
518  * from transaction.
519  *
520  * This does not affect the ownership of binder. The out parcel's ownership is passed to the caller
521  * and must be released with AParcel_delete when finished reading.
522  *
523  * Available since API level 29.
524  *
525  * \param binder the binder object to transact on.
526  * \param code the implementation-specific code representing which transaction should be taken.
527  * \param in the implementation-specific input data to this transaction.
528  * \param out the implementation-specific output data to this transaction.
529  * \param flags possible flags to alter the way in which the transaction is conducted or 0.
530  *
531  * \return the result from the kernel or from the remote process. Usually, implementation-specific
532  * error codes are written to the output parcel, and the transaction code is reserved for kernel
533  * errors or error codes that have been repeated from subsequent transactions.
534  */
535 binder_status_t AIBinder_transact(AIBinder* binder, transaction_code_t code, AParcel** in,
536                                   AParcel** out, binder_flags_t flags) __INTRODUCED_IN(29);
537 
538 /**
539  * This does not take any ownership of the input binder, but it can be used to retrieve it if
540  * something else in some process still holds a reference to it.
541  *
542  * Available since API level 29.
543  *
544  * \param binder object to create a weak pointer to.
545  *
546  * \return object representing a weak pointer to binder (or null if binder is null).
547  */
548 __attribute__((warn_unused_result)) AIBinder_Weak* AIBinder_Weak_new(AIBinder* binder)
549         __INTRODUCED_IN(29);
550 
551 /**
552  * Deletes the weak reference. This will have no impact on the lifetime of the binder.
553  *
554  * Available since API level 29.
555  *
556  * \param weakBinder object created with AIBinder_Weak_new.
557  */
558 void AIBinder_Weak_delete(AIBinder_Weak* weakBinder) __INTRODUCED_IN(29);
559 
560 /**
561  * If promotion succeeds, result will have one strong refcount added to it. Otherwise, this returns
562  * null.
563  *
564  * Available since API level 29.
565  *
566  * \param weakBinder weak pointer to attempt retrieving the original object from.
567  *
568  * \return an AIBinder object with one refcount given to the caller or null.
569  */
570 __attribute__((warn_unused_result)) AIBinder* AIBinder_Weak_promote(AIBinder_Weak* weakBinder)
571         __INTRODUCED_IN(29);
572 
573 /**
574  * This function is executed on death receipt. See AIBinder_linkToDeath/AIBinder_unlinkToDeath.
575  *
576  * Available since API level 29.
577  *
578  * \param cookie the cookie passed to AIBinder_linkToDeath.
579  */
580 typedef void (*AIBinder_DeathRecipient_onBinderDied)(void* cookie) __INTRODUCED_IN(29);
581 
582 /**
583  * This function is intended for cleaning up the data in the provided cookie, and it is executed
584  * when the DeathRecipient is unlinked. When the DeathRecipient is unlinked due to a death receipt,
585  * this method is called after the call to onBinderDied.
586  *
587  * This method is called once for each binder that is unlinked. Hence, if the same cookie is passed
588  * to multiple binders, then the caller is responsible for reference counting the cookie.
589  *
590  * See also AIBinder_linkToDeath/AIBinder_unlinkToDeath.
591  *
592  * Available since API level 33.
593  *
594  * \param cookie the cookie passed to AIBinder_linkToDeath.
595  */
596 typedef void (*AIBinder_DeathRecipient_onBinderUnlinked)(void* cookie) __INTRODUCED_IN(33);
597 
598 /**
599  * Creates a new binder death recipient. This can be attached to multiple different binder objects.
600  *
601  * Available since API level 29.
602  *
603  * \param onBinderDied the callback to call when this death recipient is invoked.
604  *
605  * \return the newly constructed object (or null if onBinderDied is null).
606  */
607 __attribute__((warn_unused_result)) AIBinder_DeathRecipient* AIBinder_DeathRecipient_new(
608         AIBinder_DeathRecipient_onBinderDied onBinderDied) __INTRODUCED_IN(29);
609 
610 /**
611  * Set the callback to be called when this DeathRecipient is unlinked from a binder. The callback is
612  * called in the following situations:
613  *
614  *  1. If the binder died, shortly after the call to onBinderDied.
615  *  2. If the binder is explicitly unlinked with AIBinder_unlinkToDeath or
616  *     AIBinder_DeathRecipient_delete.
617  *  3. During or shortly after the AIBinder_linkToDeath call if it returns an error.
618  *
619  * It is guaranteed that the callback is called exactly once for each call to linkToDeath unless the
620  * process is aborted before the binder is unlinked.
621  *
622  * Be aware that when the binder is explicitly unlinked, it is not guaranteed that onUnlinked has
623  * been called before the call to AIBinder_unlinkToDeath or AIBinder_DeathRecipient_delete returns.
624  * For example, if the binder dies concurrently with a call to AIBinder_unlinkToDeath, the binder is
625  * not unlinked until after the death notification is delivered, even if AIBinder_unlinkToDeath
626  * returns before that happens.
627  *
628  * This method should be called before linking the DeathRecipient to a binder because the function
629  * pointer is cached. If you change it after linking to a binder, it is unspecified whether the old
630  * binder will call the old or new onUnlinked callback.
631  *
632  * The onUnlinked argument may be null. In this case, no notification is given when the binder is
633  * unlinked.
634  *
635  * Available since API level 33.
636  *
637  * \param recipient the DeathRecipient to set the onUnlinked callback for.
638  * \param onUnlinked the callback to call when a binder is unlinked from recipient.
639  */
640 void AIBinder_DeathRecipient_setOnUnlinked(AIBinder_DeathRecipient* recipient,
641                                            AIBinder_DeathRecipient_onBinderUnlinked onUnlinked)
642         __INTRODUCED_IN(33);
643 
644 /**
645  * Deletes a binder death recipient. It is not necessary to call AIBinder_unlinkToDeath before
646  * calling this as these will all be automatically unlinked.
647  *
648  * Be aware that it is not safe to immediately deallocate the cookie when this call returns. If you
649  * need to clean up the cookie, you should do so in the onUnlinked callback, which can be set using
650  * AIBinder_DeathRecipient_setOnUnlinked.
651  *
652  * Available since API level 29.
653  *
654  * \param recipient the binder to delete (previously created with AIBinder_DeathRecipient_new).
655  */
656 void AIBinder_DeathRecipient_delete(AIBinder_DeathRecipient* recipient) __INTRODUCED_IN(29);
657 
658 /**
659  * Gets the extension registered with AIBinder_setExtension.
660  *
661  * See AIBinder_setExtension.
662  *
663  * Available since API level 30.
664  *
665  * \param binder the object to get the extension of.
666  * \param outExt the returned extension object. Will be null if there is no extension set or
667  * non-null with one strong ref count.
668  *
669  * \return error of getting the interface (may be a transaction error if this is
670  * remote binder). STATUS_UNEXPECTED_NULL if binder is null.
671  */
672 binder_status_t AIBinder_getExtension(AIBinder* binder, AIBinder** outExt) __INTRODUCED_IN(30);
673 
674 /**
675  * Gets the extension of a binder interface. This allows a downstream developer to add
676  * an extension to an interface without modifying its interface file. This should be
677  * called immediately when the object is created before it is passed to another thread.
678  * No thread safety is required.
679  *
680  * For instance, imagine if we have this interface:
681  *     interface IFoo { void doFoo(); }
682  *
683  * A). Historical option that has proven to be BAD! Only the original
684  *     author of an interface should change an interface. If someone
685  *     downstream wants additional functionality, they should not ever
686  *     change the interface or use this method.
687  *
688  *    BAD TO DO:  interface IFoo {                       BAD TO DO
689  *    BAD TO DO:      void doFoo();                      BAD TO DO
690  *    BAD TO DO: +    void doBar(); // adding a method   BAD TO DO
691  *    BAD TO DO:  }                                      BAD TO DO
692  *
693  * B). Option that this method enables.
694  *     Leave the original interface unchanged (do not change IFoo!).
695  *     Instead, create a new interface in a downstream package:
696  *
697  *         package com.<name>; // new functionality in a new package
698  *         interface IBar { void doBar(); }
699  *
700  *     When registering the interface, add:
701  *         std::shared_ptr<MyFoo> foo = new MyFoo; // class in AOSP codebase
702  *         std::shared_ptr<MyBar> bar = new MyBar; // custom extension class
703  *         ... = AIBinder_setExtension(foo->asBinder().get(), bar->asBinder().get());
704  *         // handle error
705  *
706  *     Then, clients of IFoo can get this extension:
707  *         SpAIBinder binder = ...;
708  *         std::shared_ptr<IFoo> foo = IFoo::fromBinder(binder); // handle if null
709  *         SpAIBinder barBinder;
710  *         ... = AIBinder_getExtension(barBinder.get());
711  *         // handle error
712  *         std::shared_ptr<IBar> bar = IBar::fromBinder(barBinder);
713  *         // type is checked with AIBinder_associateClass
714  *         // if bar is null, then there is no extension or a different
715  *         // type of extension
716  *
717  * Available since API level 30.
718  *
719  * \param binder the object to get the extension on. Must be local.
720  * \param ext the extension to set (binder will hold a strong reference to this)
721  *
722  * \return OK on success, STATUS_INVALID_OPERATION if binder is not local, STATUS_UNEXPECTED_NULL
723  * if either binder is null.
724  */
725 binder_status_t AIBinder_setExtension(AIBinder* binder, AIBinder* ext) __INTRODUCED_IN(30);
726 
727 /**
728  * Retrieve the class descriptor for the class.
729  *
730  * Available since API level 31.
731  *
732  * \param clazz the class to fetch the descriptor from
733  *
734  * \return the class descriptor string. This pointer will never be null; a
735  * descriptor is required to define a class. The pointer is owned by the class
736  * and will remain valid as long as the class does. For a local class, this will
737  * be the same value (not necessarily pointer equal) as is passed into
738  * AIBinder_Class_define. Format is utf-8.
739  */
740 const char* AIBinder_Class_getDescriptor(const AIBinder_Class* clazz) __INTRODUCED_IN(31);
741 
742 /**
743  * Whether AIBinder is less than another.
744  *
745  * This provides a per-process-unique total ordering of binders where a null
746  * AIBinder* object is considered to be before all other binder objects.
747  * For instance, two binders refer to the same object in a local or remote
748  * process when both AIBinder_lt(a, b) and AIBinder(b, a) are false. This API
749  * might be used to insert and lookup binders in binary search trees.
750  *
751  * AIBinder* pointers themselves actually also create a per-process-unique total
752  * ordering. However, this ordering is inconsistent with AIBinder_Weak_lt for
753  * remote binders. So, in general, this function should be preferred.
754  *
755  * Available since API level 31.
756  *
757  * \param lhs comparison object
758  * \param rhs comparison object
759  *
760  * \return whether "lhs < rhs" is true
761  */
762 bool AIBinder_lt(const AIBinder* lhs, const AIBinder* rhs) __INTRODUCED_IN(31);
763 
764 /**
765  * Clone an AIBinder_Weak. Useful because even if a weak binder promotes to a
766  * null value, after further binder transactions, it may no longer promote to a
767  * null value.
768  *
769  * Available since API level 31.
770  *
771  * \param weak Object to clone
772  *
773  * \return clone of the input parameter. This must be deleted with
774  * AIBinder_Weak_delete. Null if weak input parameter is also null.
775  */
776 AIBinder_Weak* AIBinder_Weak_clone(const AIBinder_Weak* weak) __INTRODUCED_IN(31);
777 
778 /**
779  * Whether AIBinder_Weak is less than another.
780  *
781  * This provides a per-process-unique total ordering of binders which is exactly
782  * the same as AIBinder_lt. Similarly, a null AIBinder_Weak* is considered to be
783  * ordered before all other weak references.
784  *
785  * This function correctly distinguishes binders even if one is deallocated. So,
786  * for instance, an AIBinder_Weak* entry representing a deleted binder will
787  * never compare as equal to an AIBinder_Weak* entry which represents a
788  * different allocation of a binder, even if the two binders were originally
789  * allocated at the same address. That is:
790  *
791  *     AIBinder* a = ...; // imagine this has address 0x8
792  *     AIBinder_Weak* bWeak = AIBinder_Weak_new(a);
793  *     AIBinder_decStrong(a); // a may be deleted, if this is the last reference
794  *     AIBinder* b = ...; // imagine this has address 0x8 (same address as b)
795  *     AIBinder_Weak* bWeak = AIBinder_Weak_new(b);
796  *
797  * Then when a/b are compared with other binders, their order will be preserved,
798  * and it will either be the case that AIBinder_Weak_lt(aWeak, bWeak) OR
799  * AIBinder_Weak_lt(bWeak, aWeak), but not both.
800  *
801  * Unlike AIBinder*, the AIBinder_Weak* addresses themselves have nothing to do
802  * with the underlying binder.
803  *
804  * Available since API level 31.
805  *
806  * \param lhs comparison object
807  * \param rhs comparison object
808  *
809  * \return whether "lhs < rhs" is true
810  */
811 bool AIBinder_Weak_lt(const AIBinder_Weak* lhs, const AIBinder_Weak* rhs) __INTRODUCED_IN(31);
812 
813 __END_DECLS
814 
815 /** @} */
816