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 * Associates a mapping of transaction codes(transaction_code_t) to function names for the given 223 * class. 224 * 225 * Trace messages will use the provided names instead of bare integer codes when set. If not set by 226 * this function, trace messages will only be identified by the bare code. This should be called one 227 * time during clazz initialization. clazz is defined using AIBinder_Class_define and 228 * transactionCodeToFunctionMap should have same scope as clazz. Resetting/clearing the 229 * transactionCodeToFunctionMap is not allowed. Passing null for either clazz or 230 * transactionCodeToFunctionMap will abort. 231 * 232 * Available since API level 36. 233 * 234 * \param clazz class which should use this transaction to code function map. 235 * \param transactionCodeToFunctionMap array of function names indexed by transaction code. 236 * Transaction codes start from 1, functions with transaction code 1 will correspond to index 0 in 237 * transactionCodeToFunctionMap. When defining methods, transaction codes are expected to be 238 * contiguous, and this is required for maximum memory efficiency. 239 * You can use nullptr if certain transaction codes are not used. Lifetime should be same as clazz. 240 * \param length number of elements in the transactionCodeToFunctionMap 241 */ 242 void AIBinder_Class_setTransactionCodeToFunctionNameMap(AIBinder_Class* clazz, 243 const char** transactionCodeToFunctionMap, 244 size_t length) __INTRODUCED_IN(36); 245 246 /** 247 * Get function name associated with transaction code for given class 248 * 249 * This function returns function name associated with provided transaction code for given class. 250 * AIBinder_Class_setTransactionCodeToFunctionNameMap should be called first to associate function 251 * to transaction code mapping. 252 * 253 * Available since API level 36. 254 * 255 * \param clazz class for which function name is requested 256 * \param transactionCode transaction_code_t for which function name is requested. 257 * 258 * \return function name in form of const char* if transaction code is valid for given class. 259 * The value returned is valid for the lifetime of clazz. if transaction code is invalid or 260 * transactionCodeToFunctionMap is not set, nullptr is returned. 261 */ 262 const char* AIBinder_Class_getFunctionName(AIBinder_Class* clazz, transaction_code_t code) 263 __INTRODUCED_IN(36); 264 265 /** 266 * This tells users of this class not to use a transaction header. By default, libbinder_ndk users 267 * read/write transaction headers implicitly (in the SDK, this must be manually written by 268 * android.os.Parcel#writeInterfaceToken, and it is read/checked with 269 * android.os.Parcel#enforceInterface). This method is provided in order to talk to legacy code 270 * which does not write an interface token. When this is disabled, type safety is reduced, so you 271 * must have a separate way of determining the binder you are talking to is the right type. Must 272 * be called before any instance of the class is created. 273 * 274 * Available since API level 33. 275 * 276 * WARNING: this API interacts badly with linkernamespaces. For correct behavior, you must 277 * use it on all instances of a class in the same process which share the same interface 278 * descriptor. In general, it is recommended you do not use this API, because it is disabling 279 * type safety. 280 * 281 * \param clazz class to disable interface header on. 282 */ 283 void AIBinder_Class_disableInterfaceTokenHeader(AIBinder_Class* clazz) __INTRODUCED_IN(33); 284 285 /** 286 * Creates a new binder object of the appropriate class. 287 * 288 * Ownership of args is passed to this object. The lifecycle is implemented with AIBinder_incStrong 289 * and AIBinder_decStrong. When the reference count reaches zero, onDestroy is called. 290 * 291 * When this is called, the refcount is implicitly 1. So, calling decStrong exactly one time is 292 * required to delete this object. 293 * 294 * Once an AIBinder object is created using this API, re-creating that AIBinder for the same 295 * instance of the same class will break pointer equality for that specific AIBinder object. For 296 * instance, if someone erroneously created two AIBinder instances representing the same callback 297 * object and passed one to a hypothetical addCallback function and then later another one to a 298 * hypothetical removeCallback function, the remote process would have no way to determine that 299 * these two objects are actually equal using the AIBinder pointer alone (which they should be able 300 * to do). Also see the suggested memory ownership model suggested above. 301 * 302 * Available since API level 29. 303 * 304 * \param clazz the type of the object to be created. 305 * \param args the args to pass to AIBinder_onCreate for that class. 306 * 307 * \return a binder object representing the newly instantiated object. 308 */ 309 __attribute__((warn_unused_result)) AIBinder* AIBinder_new(const AIBinder_Class* clazz, void* args) 310 __INTRODUCED_IN(29); 311 312 /** 313 * If this is hosted in a process other than the current one. 314 * 315 * Available since API level 29. 316 * 317 * \param binder the binder being queried. 318 * 319 * \return true if the AIBinder represents an object in another process. 320 */ 321 bool AIBinder_isRemote(const AIBinder* binder) __INTRODUCED_IN(29); 322 323 /** 324 * If this binder is known to be alive. This will not send a transaction to a remote process and 325 * returns a result based on the last known information. That is, whenever a transaction is made, 326 * this is automatically updated to reflect the current alive status of this binder. This will be 327 * updated as the result of a transaction made using AIBinder_transact, but it will also be updated 328 * based on the results of bookkeeping or other transactions made internally. 329 * 330 * Available since API level 29. 331 * 332 * \param binder the binder being queried. 333 * 334 * \return true if the binder is alive. 335 */ 336 bool AIBinder_isAlive(const AIBinder* binder) __INTRODUCED_IN(29); 337 338 /** 339 * Built-in transaction for all binder objects. This sends a transaction that will immediately 340 * return. Usually this is used to make sure that a binder is alive, as a placeholder call, or as a 341 * consistency check. 342 * 343 * Available since API level 29. 344 * 345 * \param binder the binder being queried. 346 * 347 * \return STATUS_OK if the ping succeeds. 348 */ 349 binder_status_t AIBinder_ping(AIBinder* binder) __INTRODUCED_IN(29); 350 351 /** 352 * Built-in transaction for all binder objects. This dumps information about a given binder. 353 * 354 * See also AIBinder_Class_setOnDump, AIBinder_onDump. 355 * 356 * Available since API level 29. 357 * 358 * \param binder the binder to dump information about 359 * \param fd where information should be dumped to 360 * \param args null-terminated arguments to pass (may be null if numArgs is 0) 361 * \param numArgs number of args to send 362 * 363 * \return STATUS_OK if dump succeeds (or if there is nothing to dump) 364 */ 365 binder_status_t AIBinder_dump(AIBinder* binder, int fd, const char** args, uint32_t numArgs) 366 __INTRODUCED_IN(29); 367 368 /** 369 * Registers for notifications that the associated binder is dead. The same death recipient may be 370 * associated with multiple different binders. If the binder is local, then no death recipient will 371 * be given (since if the local process dies, then no recipient will exist to receive a 372 * transaction). The cookie is passed to recipient in the case that this binder dies and can be 373 * null. The exact cookie must also be used to unlink this transaction (see AIBinder_unlinkToDeath). 374 * This function may return a binder transaction failure. The cookie can be used both for 375 * identification and holding user data. 376 * 377 * If binder is local, this will return STATUS_INVALID_OPERATION. 378 * 379 * Available since API level 29. 380 * 381 * \param binder the binder object you want to receive death notifications from. 382 * \param recipient the callback that will receive notifications when/if the binder dies. 383 * \param cookie the value that will be passed to the death recipient on death. 384 * 385 * \return STATUS_OK on success. 386 */ 387 binder_status_t AIBinder_linkToDeath(AIBinder* binder, AIBinder_DeathRecipient* recipient, 388 void* cookie) __INTRODUCED_IN(29); 389 390 /** 391 * Stops registration for the associated binder dying. Does not delete the recipient. This function 392 * may return a binder transaction failure and in case the death recipient cannot be found, it 393 * returns STATUS_NAME_NOT_FOUND. 394 * 395 * This only ever needs to be called when the AIBinder_DeathRecipient remains for use with other 396 * AIBinder objects. If the death recipient is deleted, all binders will automatically be unlinked. 397 * If the binder dies, it will automatically unlink. If the binder is deleted, it will be 398 * automatically unlinked. 399 * 400 * Be aware that it is not safe to immediately deallocate the cookie when this call returns. If you 401 * need to clean up the cookie, you should do so in the onUnlinked callback, which can be set using 402 * AIBinder_DeathRecipient_setOnUnlinked. 403 * 404 * Available since API level 29. 405 * 406 * \param binder the binder object to remove a previously linked death recipient from. 407 * \param recipient the callback to remove. 408 * \param cookie the cookie used to link to death. 409 * 410 * \return STATUS_OK on success. STATUS_NAME_NOT_FOUND if the binder cannot be found to be unlinked. 411 */ 412 binder_status_t AIBinder_unlinkToDeath(AIBinder* binder, AIBinder_DeathRecipient* recipient, 413 void* cookie) __INTRODUCED_IN(29); 414 415 /** 416 * This returns the calling UID assuming that this thread is called from a thread that is processing 417 * a binder transaction (for instance, in the implementation of AIBinder_Class_onTransact). 418 * 419 * This can be used with higher-level system services to determine the caller's identity and check 420 * permissions. 421 * 422 * Available since API level 29. 423 * 424 * \return calling uid or the current process's UID if this thread isn't processing a transaction. 425 */ 426 uid_t AIBinder_getCallingUid() __INTRODUCED_IN(29); 427 428 /** 429 * This returns the calling PID assuming that this thread is called from a thread that is processing 430 * a binder transaction (for instance, in the implementation of AIBinder_Class_onTransact). 431 * 432 * This can be used with higher-level system services to determine the caller's identity and check 433 * permissions. However, when doing this, one should be aware of possible TOCTOU problems when the 434 * calling process dies and is replaced with another process with elevated permissions and the same 435 * PID. 436 * 437 * Warning: oneway transactions do not receive PID. Even if you expect 438 * a transaction to be synchronous, a misbehaving client could send it 439 * as a synchronous call and result in a 0 PID here. Additionally, if 440 * there is a race and the calling process dies, the PID may still be 441 * 0 for a synchronous call. 442 * 443 * Available since API level 29. 444 * 445 * \return calling pid or the current process's PID if this thread isn't processing a transaction. 446 * If the transaction being processed is a oneway transaction, then this method will return 0. 447 */ 448 pid_t AIBinder_getCallingPid() __INTRODUCED_IN(29); 449 450 /** 451 * Determine whether the current thread is currently executing an incoming transaction. 452 * 453 * \return true if the current thread is currently executing an incoming transaction, and false 454 * otherwise. 455 */ 456 bool AIBinder_isHandlingTransaction() __INTRODUCED_IN(33); 457 458 /** 459 * This can only be called if a strong reference to this object already exists in process. 460 * 461 * Available since API level 29. 462 * 463 * \param binder the binder object to add a refcount to. 464 */ 465 void AIBinder_incStrong(AIBinder* binder) __INTRODUCED_IN(29); 466 467 /** 468 * This will delete the object and call onDestroy once the refcount reaches zero. 469 * 470 * Available since API level 29. 471 * 472 * \param binder the binder object to remove a refcount from. 473 */ 474 void AIBinder_decStrong(AIBinder* binder) __INTRODUCED_IN(29); 475 476 /** 477 * For debugging only! 478 * 479 * Available since API level 29. 480 * 481 * \param binder the binder object to retrieve the refcount of. 482 * 483 * \return the number of strong-refs on this binder in this process. If binder is null, this will be 484 * -1. 485 */ 486 int32_t AIBinder_debugGetRefCount(AIBinder* binder) __INTRODUCED_IN(29); 487 488 /** 489 * This sets the class of an AIBinder object. This checks to make sure the remote object is of 490 * the expected class. A class must be set in order to use transactions on an AIBinder object. 491 * However, if an object is just intended to be passed through to another process or used as a 492 * handle this need not be called. 493 * 494 * This returns true if the class association succeeds. If it fails, no change is made to the 495 * binder object. 496 * 497 * Warning: this may fail if the binder is dead. 498 * 499 * Available since API level 29. 500 * 501 * \param binder the object to attach the class to. 502 * \param clazz the clazz to attach to binder. 503 * 504 * \return true if the binder has the class clazz and if the association was successful. 505 */ 506 bool AIBinder_associateClass(AIBinder* binder, const AIBinder_Class* clazz) __INTRODUCED_IN(29); 507 508 /** 509 * Returns the class that this binder was constructed with or associated with. 510 * 511 * Available since API level 29. 512 * 513 * \param binder the object that is being queried. 514 * 515 * \return the class that this binder is associated with. If this binder wasn't created with 516 * AIBinder_new, and AIBinder_associateClass hasn't been called, then this will return null. 517 */ 518 const AIBinder_Class* AIBinder_getClass(AIBinder* binder) __INTRODUCED_IN(29); 519 520 /** 521 * Value returned by onCreate for a local binder. For stateless classes (if onCreate returns 522 * null), this also returns null. For a remote binder, this will always return null. 523 * 524 * Available since API level 29. 525 * 526 * \param binder the object that is being queried. 527 * 528 * \return the userdata returned from AIBinder_onCreate when this object was created. This may be 529 * null for stateless objects. For remote objects, this is always null. 530 */ 531 void* AIBinder_getUserData(AIBinder* binder) __INTRODUCED_IN(29); 532 533 /** 534 * A transaction is a series of calls to these functions which looks this 535 * - call AIBinder_prepareTransaction 536 * - fill out the in parcel with parameters (lifetime of the 'in' variable) 537 * - call AIBinder_transact 538 * - read results from the out parcel (lifetime of the 'out' variable) 539 */ 540 541 /** 542 * Creates a parcel to start filling out for a transaction. This will add a header to the 543 * transaction that corresponds to android.os.Parcel#writeInterfaceToken. This may add debugging 544 * or other information to the transaction for platform use or to enable other features to work. The 545 * contents of this header is a platform implementation detail, and it is required to use 546 * libbinder_ndk. This parcel is to be sent via AIBinder_transact and it represents the input data 547 * to the transaction. It is recommended to check if the object is local and call directly into its 548 * user data before calling this as the parceling and unparceling cost can be avoided. This AIBinder 549 * must be either built with a class or associated with a class before using this API. 550 * 551 * This does not affect the ownership of binder. When this function succeeds, the in parcel's 552 * ownership is passed to the caller. At this point, the parcel can be filled out and passed to 553 * AIBinder_transact. Alternatively, if there is an error while filling out the parcel, it can be 554 * deleted with AParcel_delete. 555 * 556 * Available since API level 29. 557 * 558 * \param binder the binder object to start a transaction on. 559 * \param in out parameter for input data to the transaction. 560 * 561 * \return STATUS_OK on success. This will return STATUS_INVALID_OPERATION if the binder has not yet 562 * been associated with a class (see AIBinder_new and AIBinder_associateClass). 563 */ 564 binder_status_t AIBinder_prepareTransaction(AIBinder* binder, AParcel** in) __INTRODUCED_IN(29); 565 566 /** 567 * Transact using a parcel created from AIBinder_prepareTransaction. This actually communicates with 568 * the object representing this binder object. This also passes out a parcel to be used for the 569 * return transaction. This takes ownership of the in parcel and automatically deletes it after it 570 * is sent to the remote process. The output parcel is the result of the transaction. If the 571 * transaction has FLAG_ONEWAY, the out parcel will be empty. Otherwise, this will block until the 572 * remote process has processed the transaction, and the out parcel will contain the output data 573 * from transaction. 574 * 575 * This does not affect the ownership of binder. The out parcel's ownership is passed to the caller 576 * and must be released with AParcel_delete when finished reading. 577 * 578 * Available since API level 29. 579 * 580 * \param binder the binder object to transact on. 581 * \param code the implementation-specific code representing which transaction should be taken. 582 * \param in the implementation-specific input data to this transaction. 583 * \param out the implementation-specific output data to this transaction. 584 * \param flags possible flags to alter the way in which the transaction is conducted or 0. 585 * 586 * \return the result from the kernel or from the remote process. Usually, implementation-specific 587 * error codes are written to the output parcel, and the transaction code is reserved for kernel 588 * errors or error codes that have been repeated from subsequent transactions. 589 */ 590 binder_status_t AIBinder_transact(AIBinder* binder, transaction_code_t code, AParcel** in, 591 AParcel** out, binder_flags_t flags) __INTRODUCED_IN(29); 592 593 /** 594 * This does not take any ownership of the input binder, but it can be used to retrieve it if 595 * something else in some process still holds a reference to it. 596 * 597 * Available since API level 29. 598 * 599 * \param binder object to create a weak pointer to. 600 * 601 * \return object representing a weak pointer to binder (or null if binder is null). 602 */ 603 __attribute__((warn_unused_result)) AIBinder_Weak* AIBinder_Weak_new(AIBinder* binder) 604 __INTRODUCED_IN(29); 605 606 /** 607 * Deletes the weak reference. This will have no impact on the lifetime of the binder. 608 * 609 * Available since API level 29. 610 * 611 * \param weakBinder object created with AIBinder_Weak_new. 612 */ 613 void AIBinder_Weak_delete(AIBinder_Weak* weakBinder) __INTRODUCED_IN(29); 614 615 /** 616 * If promotion succeeds, result will have one strong refcount added to it. Otherwise, this returns 617 * null. 618 * 619 * Available since API level 29. 620 * 621 * \param weakBinder weak pointer to attempt retrieving the original object from. 622 * 623 * \return an AIBinder object with one refcount given to the caller or null. 624 */ 625 __attribute__((warn_unused_result)) AIBinder* AIBinder_Weak_promote(AIBinder_Weak* weakBinder) 626 __INTRODUCED_IN(29); 627 628 /** 629 * This function is executed on death receipt. See AIBinder_linkToDeath/AIBinder_unlinkToDeath. 630 * 631 * Available since API level 29. 632 * 633 * \param cookie the cookie passed to AIBinder_linkToDeath. 634 */ 635 typedef void (*AIBinder_DeathRecipient_onBinderDied)(void* cookie) __INTRODUCED_IN(29); 636 637 /** 638 * This function is intended for cleaning up the data in the provided cookie, and it is executed 639 * when the DeathRecipient is unlinked. When the DeathRecipient is unlinked due to a death receipt, 640 * this method is called after the call to onBinderDied. 641 * 642 * This method is called once for each binder that is unlinked. Hence, if the same cookie is passed 643 * to multiple binders, then the caller is responsible for reference counting the cookie. 644 * 645 * See also AIBinder_linkToDeath/AIBinder_unlinkToDeath. 646 * 647 * WARNING: Make sure the lifetime of this cookie is long enough. If it is dynamically 648 * allocated, it should be deleted with AIBinder_DeathRecipient_setOnUnlinked. 649 * 650 * Available since API level 33. 651 * 652 * \param cookie the cookie passed to AIBinder_linkToDeath. 653 */ 654 typedef void (*AIBinder_DeathRecipient_onBinderUnlinked)(void* cookie) __INTRODUCED_IN(33); 655 656 /** 657 * Creates a new binder death recipient. This can be attached to multiple different binder objects. 658 * 659 * Available since API level 29. 660 * 661 * WARNING: Make sure the lifetime of this cookie is long enough. If it is dynamically 662 * allocated, it should be deleted with AIBinder_DeathRecipient_setOnUnlinked. 663 * 664 * \param onBinderDied the callback to call when this death recipient is invoked. 665 * 666 * \return the newly constructed object (or null if onBinderDied is null). 667 */ 668 __attribute__((warn_unused_result)) AIBinder_DeathRecipient* AIBinder_DeathRecipient_new( 669 AIBinder_DeathRecipient_onBinderDied onBinderDied) __INTRODUCED_IN(29); 670 671 /** 672 * Set the callback to be called when this DeathRecipient is unlinked from a binder. The callback is 673 * called in the following situations: 674 * 675 * 1. If the binder died, shortly after the call to onBinderDied. 676 * 2. If the binder is explicitly unlinked with AIBinder_unlinkToDeath or 677 * AIBinder_DeathRecipient_delete, after any pending onBinderDied calls 678 * finish. 679 * 3. During or shortly after the AIBinder_linkToDeath call if it returns an error. 680 * 681 * It is guaranteed that the callback is called exactly once for each call to linkToDeath unless the 682 * process is aborted before the binder is unlinked. 683 * 684 * Be aware that when the binder is explicitly unlinked, it is not guaranteed that onUnlinked has 685 * been called before the call to AIBinder_unlinkToDeath or AIBinder_DeathRecipient_delete returns. 686 * For example, if the binder dies concurrently with a call to AIBinder_unlinkToDeath, the binder is 687 * not unlinked until after the death notification is delivered, even if AIBinder_unlinkToDeath 688 * returns before that happens. 689 * 690 * This method should be called before linking the DeathRecipient to a binder because the function 691 * pointer is cached. If you change it after linking to a binder, it is unspecified whether the old 692 * binder will call the old or new onUnlinked callback. 693 * 694 * The onUnlinked argument may be null. In this case, no notification is given when the binder is 695 * unlinked. 696 * 697 * Available since API level 33. 698 * 699 * \param recipient the DeathRecipient to set the onUnlinked callback for. 700 * \param onUnlinked the callback to call when a binder is unlinked from recipient. 701 */ 702 void AIBinder_DeathRecipient_setOnUnlinked(AIBinder_DeathRecipient* recipient, 703 AIBinder_DeathRecipient_onBinderUnlinked onUnlinked) 704 __INTRODUCED_IN(33); 705 706 /** 707 * Deletes a binder death recipient. It is not necessary to call AIBinder_unlinkToDeath before 708 * calling this as these will all be automatically unlinked. 709 * 710 * Be aware that it is not safe to immediately deallocate the cookie when this call returns. If you 711 * need to clean up the cookie, you should do so in the onUnlinked callback, which can be set using 712 * AIBinder_DeathRecipient_setOnUnlinked. 713 * 714 * Available since API level 29. 715 * 716 * \param recipient the binder to delete (previously created with AIBinder_DeathRecipient_new). 717 */ 718 void AIBinder_DeathRecipient_delete(AIBinder_DeathRecipient* recipient) __INTRODUCED_IN(29); 719 720 /** 721 * Gets the extension registered with AIBinder_setExtension. 722 * 723 * See AIBinder_setExtension. 724 * 725 * Available since API level 30. 726 * 727 * \param binder the object to get the extension of. 728 * \param outExt the returned extension object. Will be null if there is no extension set or 729 * non-null with one strong ref count. 730 * 731 * \return error of getting the interface (may be a transaction error if this is 732 * remote binder). STATUS_UNEXPECTED_NULL if binder is null. 733 */ 734 binder_status_t AIBinder_getExtension(AIBinder* binder, AIBinder** outExt) __INTRODUCED_IN(30); 735 736 /** 737 * Gets the extension of a binder interface. This allows a downstream developer to add 738 * an extension to an interface without modifying its interface file. This should be 739 * called immediately when the object is created before it is passed to another thread. 740 * No thread safety is required. 741 * 742 * For instance, imagine if we have this interface: 743 * interface IFoo { void doFoo(); } 744 * 745 * A). Historical option that has proven to be BAD! Only the original 746 * author of an interface should change an interface. If someone 747 * downstream wants additional functionality, they should not ever 748 * change the interface or use this method. 749 * 750 * BAD TO DO: interface IFoo { BAD TO DO 751 * BAD TO DO: void doFoo(); BAD TO DO 752 * BAD TO DO: + void doBar(); // adding a method BAD TO DO 753 * BAD TO DO: } BAD TO DO 754 * 755 * B). Option that this method enables. 756 * Leave the original interface unchanged (do not change IFoo!). 757 * Instead, create a new interface in a downstream package: 758 * 759 * package com.<name>; // new functionality in a new package 760 * interface IBar { void doBar(); } 761 * 762 * When registering the interface, add: 763 * std::shared_ptr<MyFoo> foo = new MyFoo; // class in AOSP codebase 764 * std::shared_ptr<MyBar> bar = new MyBar; // custom extension class 765 * SpAIBinder binder = foo->asBinder(); // target binder to extend 766 * ... = AIBinder_setExtension(binder.get(), bar->asBinder().get()); 767 * ... = AServiceManager_addService(binder.get(), instanceName); 768 * // handle error 769 * 770 * Do not use foo->asBinder().get() as the target binder argument to 771 * AIBinder_setExtensions because asBinder it creates a new binder 772 * object that will be destroyed after the function is called. The same 773 * binder object must be used for AIBinder_setExtension and 774 * AServiceManager_addService to register the service with an extension. 775 * 776 * Then, clients of IFoo can get this extension: 777 * SpAIBinder binder = ...; 778 * std::shared_ptr<IFoo> foo = IFoo::fromBinder(binder); // handle if null 779 * SpAIBinder barBinder; 780 * ... = AIBinder_getExtension(barBinder.get()); 781 * // handle error 782 * std::shared_ptr<IBar> bar = IBar::fromBinder(barBinder); 783 * // type is checked with AIBinder_associateClass 784 * // if bar is null, then there is no extension or a different 785 * // type of extension 786 * 787 * Available since API level 30. 788 * 789 * \param binder the object to get the extension on. Must be local. 790 * \param ext the extension to set (binder will hold a strong reference to this) 791 * 792 * \return OK on success, STATUS_INVALID_OPERATION if binder is not local, STATUS_UNEXPECTED_NULL 793 * if either binder is null. 794 */ 795 binder_status_t AIBinder_setExtension(AIBinder* binder, AIBinder* ext) __INTRODUCED_IN(30); 796 797 /** 798 * Retrieve the class descriptor for the class. 799 * 800 * Available since API level 31. 801 * 802 * \param clazz the class to fetch the descriptor from 803 * 804 * \return the class descriptor string. This pointer will never be null; a 805 * descriptor is required to define a class. The pointer is owned by the class 806 * and will remain valid as long as the class does. For a local class, this will 807 * be the same value (not necessarily pointer equal) as is passed into 808 * AIBinder_Class_define. Format is utf-8. 809 */ 810 const char* AIBinder_Class_getDescriptor(const AIBinder_Class* clazz) __INTRODUCED_IN(31); 811 812 /** 813 * Whether AIBinder is less than another. 814 * 815 * This provides a per-process-unique total ordering of binders where a null 816 * AIBinder* object is considered to be before all other binder objects. 817 * For instance, two binders refer to the same object in a local or remote 818 * process when both AIBinder_lt(a, b) and AIBinder_lt(b, a) are false. This API 819 * might be used to insert and lookup binders in binary search trees. 820 * 821 * AIBinder* pointers themselves actually also create a per-process-unique total 822 * ordering. However, this ordering is inconsistent with AIBinder_Weak_lt for 823 * remote binders. So, in general, this function should be preferred. 824 * 825 * Available since API level 31. 826 * 827 * \param lhs comparison object 828 * \param rhs comparison object 829 * 830 * \return whether "lhs < rhs" is true 831 */ 832 bool AIBinder_lt(const AIBinder* lhs, const AIBinder* rhs) __INTRODUCED_IN(31); 833 834 /** 835 * Clone an AIBinder_Weak. Useful because even if a weak binder promotes to a 836 * null value, after further binder transactions, it may no longer promote to a 837 * null value. 838 * 839 * Available since API level 31. 840 * 841 * \param weak Object to clone 842 * 843 * \return clone of the input parameter. This must be deleted with 844 * AIBinder_Weak_delete. Null if weak input parameter is also null. 845 */ 846 AIBinder_Weak* AIBinder_Weak_clone(const AIBinder_Weak* weak) __INTRODUCED_IN(31); 847 848 /** 849 * Whether AIBinder_Weak is less than another. 850 * 851 * This provides a per-process-unique total ordering of binders which is exactly 852 * the same as AIBinder_lt. Similarly, a null AIBinder_Weak* is considered to be 853 * ordered before all other weak references. 854 * 855 * This function correctly distinguishes binders even if one is deallocated. So, 856 * for instance, an AIBinder_Weak* entry representing a deleted binder will 857 * never compare as equal to an AIBinder_Weak* entry which represents a 858 * different allocation of a binder, even if the two binders were originally 859 * allocated at the same address. That is: 860 * 861 * AIBinder* a = ...; // imagine this has address 0x8 862 * AIBinder_Weak* bWeak = AIBinder_Weak_new(a); 863 * AIBinder_decStrong(a); // a may be deleted, if this is the last reference 864 * AIBinder* b = ...; // imagine this has address 0x8 (same address as b) 865 * AIBinder_Weak* bWeak = AIBinder_Weak_new(b); 866 * 867 * Then when a/b are compared with other binders, their order will be preserved, 868 * and it will either be the case that AIBinder_Weak_lt(aWeak, bWeak) OR 869 * AIBinder_Weak_lt(bWeak, aWeak), but not both. 870 * 871 * Unlike AIBinder*, the AIBinder_Weak* addresses themselves have nothing to do 872 * with the underlying binder. 873 * 874 * Available since API level 31. 875 * 876 * \param lhs comparison object 877 * \param rhs comparison object 878 * 879 * \return whether "lhs < rhs" is true 880 */ 881 bool AIBinder_Weak_lt(const AIBinder_Weak* lhs, const AIBinder_Weak* rhs) __INTRODUCED_IN(31); 882 883 __END_DECLS 884 885 /** @} */ 886