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 <stdint.h> 30 #include <sys/cdefs.h> 31 #include <sys/types.h> 32 33 #include <android/binder_parcel.h> 34 #include <android/binder_status.h> 35 36 __BEGIN_DECLS 37 38 #ifndef __ANDROID_API__ 39 #error Android builds must be compiled against a specific API. If this is an \ 40 android platform host build, you must use libbinder_ndk_host_user. 41 #endif 42 43 #if __ANDROID_API__ >= 29 44 45 // Also see TF_* in kernel's binder.h 46 typedef uint32_t binder_flags_t; 47 enum { 48 /** 49 * The transaction will be dispatched and then returned to the caller. The outgoing process 50 * cannot block a call made by this, and execution of the call will not be waited on. An error 51 * can still be returned if the call is unable to be processed by the binder driver. All oneway 52 * calls are guaranteed to be ordered if they are sent on the same AIBinder object. 53 */ 54 FLAG_ONEWAY = 0x01, 55 }; 56 57 // Also see IBinder.h in libbinder 58 typedef uint32_t transaction_code_t; 59 enum { 60 /** 61 * The first transaction code available for user commands (inclusive). 62 */ 63 FIRST_CALL_TRANSACTION = 0x00000001, 64 /** 65 * The last transaction code available for user commands (inclusive). 66 */ 67 LAST_CALL_TRANSACTION = 0x00ffffff, 68 }; 69 70 /** 71 * Represents a type of AIBinder object which can be sent out. 72 */ 73 struct AIBinder_Class; 74 typedef struct AIBinder_Class AIBinder_Class; 75 76 /** 77 * Represents a local or remote object which can be used for IPC or which can itself be sent. 78 * 79 * This object has a refcount associated with it and will be deleted when its refcount reaches zero. 80 * How methods interactive with this refcount is described below. When using this API, it is 81 * intended for a client of a service to hold a strong reference to that service. This also means 82 * that user data typically should hold a strong reference to a local AIBinder object. A remote 83 * AIBinder object automatically holds a strong reference to the AIBinder object in the server's 84 * process. A typically memory layout looks like this: 85 * 86 * Key: 87 * ---> Ownership/a strong reference 88 * ...> A weak reference 89 * 90 * (process boundary) 91 * | 92 * MyInterface ---> AIBinder_Weak | ProxyForMyInterface 93 * ^ . | | 94 * | . | | 95 * | v | v 96 * UserData <--- AIBinder <-|- AIBinder 97 * | 98 * 99 * In this way, you'll notice that a proxy for the interface holds a strong reference to the 100 * implementation and that in the server process, the AIBinder object which was sent can be resent 101 * so that the same AIBinder object always represents the same object. This allows, for instance, an 102 * implementation (usually a callback) to transfer all ownership to a remote process and 103 * automatically be deleted when the remote process is done with it or dies. Other memory models are 104 * possible, but this is the standard one. 105 * 106 * If the process containing an AIBinder dies, it is possible to be holding a strong reference to 107 * an object which does not exist. In this case, transactions to this binder will return 108 * STATUS_DEAD_OBJECT. See also AIBinder_linkToDeath, AIBinder_unlinkToDeath, and AIBinder_isAlive. 109 * 110 * Once an AIBinder is created, anywhere it is passed (remotely or locally), there is a 1-1 111 * correspondence between the address of an AIBinder and the object it represents. This means that 112 * when two AIBinder pointers point to the same address, they represent the same object (whether 113 * that object is local or remote). This correspondance can be broken accidentally if AIBinder_new 114 * is erronesouly called to create the same object multiple times. 115 */ 116 struct AIBinder; 117 typedef struct AIBinder AIBinder; 118 119 /** 120 * The AIBinder object associated with this can be retrieved if it is still alive so that it can be 121 * re-used. The intention of this is to enable the same AIBinder object to always represent the same 122 * object. 123 */ 124 struct AIBinder_Weak; 125 typedef struct AIBinder_Weak AIBinder_Weak; 126 127 /** 128 * Represents a handle on a death notification. See AIBinder_linkToDeath/AIBinder_unlinkToDeath. 129 */ 130 struct AIBinder_DeathRecipient; 131 typedef struct AIBinder_DeathRecipient AIBinder_DeathRecipient; 132 133 /** 134 * This is called whenever a new AIBinder object is needed of a specific class. 135 * 136 * \param args these can be used to construct a new class. These are passed from AIBinder_new. 137 * \return this is the userdata representing the class. It can be retrieved using 138 * AIBinder_getUserData. 139 */ 140 typedef void* (*AIBinder_Class_onCreate)(void* args); 141 142 /** 143 * This is called whenever an AIBinder object is no longer referenced and needs destroyed. 144 * 145 * Typically, this just deletes whatever the implementation is. 146 * 147 * \param userData this is the same object returned by AIBinder_Class_onCreate 148 */ 149 typedef void (*AIBinder_Class_onDestroy)(void* userData); 150 151 /** 152 * This is called whenever a transaction needs to be processed by a local implementation. 153 * 154 * \param binder the object being transacted on. 155 * \param code implementation-specific code representing which transaction should be taken. 156 * \param in the implementation-specific input data to this transaction. 157 * \param out the implementation-specific output data to this transaction. 158 * 159 * \return the implementation-specific output code. This may be forwarded from another service, the 160 * result of a parcel read or write, or another error as is applicable to the specific 161 * implementation. Usually, implementation-specific error codes are written to the output parcel, 162 * and the transaction code is reserved for kernel errors or error codes that have been repeated 163 * from subsequent transactions. 164 */ 165 typedef binder_status_t (*AIBinder_Class_onTransact)(AIBinder* binder, transaction_code_t code, 166 const AParcel* in, AParcel* out); 167 168 /** 169 * This creates a new instance of a class of binders which can be instantiated. This is called one 170 * time during library initialization and cleaned up when the process exits or execs. 171 * 172 * None of these parameters can be null. 173 * 174 * Available since API level 29. 175 * 176 * \param interfaceDescriptor this is a unique identifier for the class. This is used internally for 177 * sanity checks on transactions. 178 * \param onCreate see AIBinder_Class_onCreate. 179 * \param onDestroy see AIBinder_Class_onDestroy. 180 * \param onTransact see AIBinder_Class_onTransact. 181 * 182 * \return the class object representing these parameters or null on error. 183 */ 184 __attribute__((warn_unused_result)) AIBinder_Class* AIBinder_Class_define( 185 const char* interfaceDescriptor, AIBinder_Class_onCreate onCreate, 186 AIBinder_Class_onDestroy onDestroy, AIBinder_Class_onTransact onTransact) 187 __INTRODUCED_IN(29); 188 189 /** 190 * Dump information about an AIBinder (usually for debugging). 191 * 192 * When no arguments are provided, a brief overview of the interview should be given. 193 * 194 * \param binder interface being dumped 195 * \param fd file descriptor to be dumped to, should be flushed, ownership is not passed. 196 * \param args array of null-terminated strings for dump (may be null if numArgs is 0) 197 * \param numArgs number of args to be sent 198 * 199 * \return binder_status_t result of transaction (if remote, for instance) 200 */ 201 typedef binder_status_t (*AIBinder_onDump)(AIBinder* binder, int fd, const char** args, 202 uint32_t numArgs); 203 204 /** 205 * This sets the implementation of the dump method for a class. 206 * 207 * If this isn't set, nothing will be dumped when dump is called (for instance with 208 * android.os.Binder#dump). Must be called before any instance of the class is created. 209 * 210 * Available since API level 29. 211 * 212 * \param dump function to call when an instance of this binder class is being dumped. 213 */ 214 void AIBinder_Class_setOnDump(AIBinder_Class* clazz, AIBinder_onDump onDump) __INTRODUCED_IN(29); 215 216 /** 217 * Creates a new binder object of the appropriate class. 218 * 219 * Ownership of args is passed to this object. The lifecycle is implemented with AIBinder_incStrong 220 * and AIBinder_decStrong. When the reference count reaches zero, onDestroy is called. 221 * 222 * When this is called, the refcount is implicitly 1. So, calling decStrong exactly one time is 223 * required to delete this object. 224 * 225 * Once an AIBinder object is created using this API, re-creating that AIBinder for the same 226 * instance of the same class will break pointer equality for that specific AIBinder object. For 227 * instance, if someone erroneously created two AIBinder instances representing the same callback 228 * object and passed one to a hypothetical addCallback function and then later another one to a 229 * hypothetical removeCallback function, the remote process would have no way to determine that 230 * these two objects are actually equal using the AIBinder pointer alone (which they should be able 231 * to do). Also see the suggested memory ownership model suggested above. 232 * 233 * Available since API level 29. 234 * 235 * \param clazz the type of the object to be created. 236 * \param args the args to pass to AIBinder_onCreate for that class. 237 * 238 * \return a binder object representing the newly instantiated object. 239 */ 240 __attribute__((warn_unused_result)) AIBinder* AIBinder_new(const AIBinder_Class* clazz, void* args) 241 __INTRODUCED_IN(29); 242 243 /** 244 * If this is hosted in a process other than the current one. 245 * 246 * Available since API level 29. 247 * 248 * \param binder the binder being queried. 249 * 250 * \return true if the AIBinder represents an object in another process. 251 */ 252 bool AIBinder_isRemote(const AIBinder* binder) __INTRODUCED_IN(29); 253 254 /** 255 * If this binder is known to be alive. This will not send a transaction to a remote process and 256 * returns a result based on the last known information. That is, whenever a transaction is made, 257 * this is automatically updated to reflect the current alive status of this binder. This will be 258 * updated as the result of a transaction made using AIBinder_transact, but it will also be updated 259 * based on the results of bookkeeping or other transactions made internally. 260 * 261 * Available since API level 29. 262 * 263 * \param binder the binder being queried. 264 * 265 * \return true if the binder is alive. 266 */ 267 bool AIBinder_isAlive(const AIBinder* binder) __INTRODUCED_IN(29); 268 269 /** 270 * Built-in transaction for all binder objects. This sends a transaction that will immediately 271 * return. Usually this is used to make sure that a binder is alive, as a placeholder call, or as a 272 * sanity check. 273 * 274 * Available since API level 29. 275 * 276 * \param binder the binder being queried. 277 * 278 * \return STATUS_OK if the ping succeeds. 279 */ 280 binder_status_t AIBinder_ping(AIBinder* binder) __INTRODUCED_IN(29); 281 282 /** 283 * Built-in transaction for all binder objects. This dumps information about a given binder. 284 * 285 * See also AIBinder_Class_setOnDump, AIBinder_onDump. 286 * 287 * Available since API level 29. 288 * 289 * \param binder the binder to dump information about 290 * \param fd where information should be dumped to 291 * \param args null-terminated arguments to pass (may be null if numArgs is 0) 292 * \param numArgs number of args to send 293 * 294 * \return STATUS_OK if dump succeeds (or if there is nothing to dump) 295 */ 296 binder_status_t AIBinder_dump(AIBinder* binder, int fd, const char** args, uint32_t numArgs) 297 __INTRODUCED_IN(29); 298 299 /** 300 * Registers for notifications that the associated binder is dead. The same death recipient may be 301 * associated with multiple different binders. If the binder is local, then no death recipient will 302 * be given (since if the local process dies, then no recipient will exist to recieve a 303 * transaction). The cookie is passed to recipient in the case that this binder dies and can be 304 * null. The exact cookie must also be used to unlink this transaction (see AIBinder_linkToDeath). 305 * This function may return a binder transaction failure. The cookie can be used both for 306 * identification and holding user data. 307 * 308 * If binder is local, this will return STATUS_INVALID_OPERATION. 309 * 310 * Available since API level 29. 311 * 312 * \param binder the binder object you want to receive death notifications from. 313 * \param recipient the callback that will receive notifications when/if the binder dies. 314 * \param cookie the value that will be passed to the death recipient on death. 315 * 316 * \return STATUS_OK on success. 317 */ 318 binder_status_t AIBinder_linkToDeath(AIBinder* binder, AIBinder_DeathRecipient* recipient, 319 void* cookie) __INTRODUCED_IN(29); 320 321 /** 322 * Stops registration for the associated binder dying. Does not delete the recipient. This function 323 * may return a binder transaction failure and in case the death recipient cannot be found, it 324 * returns STATUS_NAME_NOT_FOUND. 325 * 326 * This only ever needs to be called when the AIBinder_DeathRecipient remains for use with other 327 * AIBinder objects. If the death recipient is deleted, all binders will automatically be unlinked. 328 * If the binder dies, it will automatically unlink. If the binder is deleted, it will be 329 * automatically unlinked. 330 * 331 * Available since API level 29. 332 * 333 * \param binder the binder object to remove a previously linked death recipient from. 334 * \param recipient the callback to remove. 335 * \param cookie the cookie used to link to death. 336 * 337 * \return STATUS_OK on success. STATUS_NAME_NOT_FOUND if the binder cannot be found to be unlinked. 338 */ 339 binder_status_t AIBinder_unlinkToDeath(AIBinder* binder, AIBinder_DeathRecipient* recipient, 340 void* cookie) __INTRODUCED_IN(29); 341 342 /** 343 * This returns the calling UID assuming that this thread is called from a thread that is processing 344 * a binder transaction (for instance, in the implementation of AIBinder_Class_onTransact). 345 * 346 * This can be used with higher-level system services to determine the caller's identity and check 347 * permissions. 348 * 349 * Available since API level 29. 350 * 351 * \return calling uid or the current process's UID if this thread isn't processing a transaction. 352 */ 353 uid_t AIBinder_getCallingUid() __INTRODUCED_IN(29); 354 355 /** 356 * This returns the calling PID assuming that this thread is called from a thread that is processing 357 * a binder transaction (for instance, in the implementation of AIBinder_Class_onTransact). 358 * 359 * This can be used with higher-level system services to determine the caller's identity and check 360 * permissions. However, when doing this, one should be aware of possible TOCTOU problems when the 361 * calling process dies and is replaced with another process with elevated permissions and the same 362 * PID. 363 * 364 * Available since API level 29. 365 * 366 * \return calling pid or the current process's PID if this thread isn't processing a transaction. 367 * If the transaction being processed is a oneway transaction, then this method will return 0. 368 */ 369 pid_t AIBinder_getCallingPid() __INTRODUCED_IN(29); 370 371 /** 372 * This can only be called if a strong reference to this object already exists in process. 373 * 374 * Available since API level 29. 375 * 376 * \param binder the binder object to add a refcount to. 377 */ 378 void AIBinder_incStrong(AIBinder* binder) __INTRODUCED_IN(29); 379 380 /** 381 * This will delete the object and call onDestroy once the refcount reaches zero. 382 * 383 * Available since API level 29. 384 * 385 * \param binder the binder object to remove a refcount from. 386 */ 387 void AIBinder_decStrong(AIBinder* binder) __INTRODUCED_IN(29); 388 389 /** 390 * For debugging only! 391 * 392 * Available since API level 29. 393 * 394 * \param binder the binder object to retrieve the refcount of. 395 * 396 * \return the number of strong-refs on this binder in this process. If binder is null, this will be 397 * -1. 398 */ 399 int32_t AIBinder_debugGetRefCount(AIBinder* binder) __INTRODUCED_IN(29); 400 401 /** 402 * This sets the class of an AIBinder object. This checks to make sure the remote object is of 403 * the expected class. A class must be set in order to use transactions on an AIBinder object. 404 * However, if an object is just intended to be passed through to another process or used as a 405 * handle this need not be called. 406 * 407 * This returns true if the class association succeeds. If it fails, no change is made to the 408 * binder object. 409 * 410 * Available since API level 29. 411 * 412 * \param binder the object to attach the class to. 413 * \param clazz the clazz to attach to binder. 414 * 415 * \return true if the binder has the class clazz and if the association was successful. 416 */ 417 bool AIBinder_associateClass(AIBinder* binder, const AIBinder_Class* clazz) __INTRODUCED_IN(29); 418 419 /** 420 * Returns the class that this binder was constructed with or associated with. 421 * 422 * Available since API level 29. 423 * 424 * \param binder the object that is being queried. 425 * 426 * \return the class that this binder is associated with. If this binder wasn't created with 427 * AIBinder_new, and AIBinder_associateClass hasn't been called, then this will return null. 428 */ 429 const AIBinder_Class* AIBinder_getClass(AIBinder* binder) __INTRODUCED_IN(29); 430 431 /** 432 * Value returned by onCreate for a local binder. For stateless classes (if onCreate returns 433 * null), this also returns null. For a remote binder, this will always return null. 434 * 435 * Available since API level 29. 436 * 437 * \param binder the object that is being queried. 438 * 439 * \return the userdata returned from AIBinder_onCreate when this object was created. This may be 440 * null for stateless objects. For remote objects, this is always null. 441 */ 442 void* AIBinder_getUserData(AIBinder* binder) __INTRODUCED_IN(29); 443 444 /** 445 * A transaction is a series of calls to these functions which looks this 446 * - call AIBinder_prepareTransaction 447 * - fill out the in parcel with parameters (lifetime of the 'in' variable) 448 * - call AIBinder_transact 449 * - read results from the out parcel (lifetime of the 'out' variable) 450 */ 451 452 /** 453 * Creates a parcel to start filling out for a transaction. This may add data to the parcel for 454 * security, debugging, or other purposes. This parcel is to be sent via AIBinder_transact and it 455 * represents the input data to the transaction. It is recommended to check if the object is local 456 * and call directly into its user data before calling this as the parceling and unparceling cost 457 * can be avoided. This AIBinder must be either built with a class or associated with a class before 458 * using this API. 459 * 460 * This does not affect the ownership of binder. When this function succeeds, the in parcel's 461 * ownership is passed to the caller. At this point, the parcel can be filled out and passed to 462 * AIBinder_transact. Alternatively, if there is an error while filling out the parcel, it can be 463 * deleted with AParcel_delete. 464 * 465 * Available since API level 29. 466 * 467 * \param binder the binder object to start a transaction on. 468 * \param in out parameter for input data to the transaction. 469 * 470 * \return STATUS_OK on success. This will return STATUS_INVALID_OPERATION if the binder has not yet 471 * been associated with a class (see AIBinder_new and AIBinder_associateClass). 472 */ 473 binder_status_t AIBinder_prepareTransaction(AIBinder* binder, AParcel** in) __INTRODUCED_IN(29); 474 475 /** 476 * Transact using a parcel created from AIBinder_prepareTransaction. This actually communicates with 477 * the object representing this binder object. This also passes out a parcel to be used for the 478 * return transaction. This takes ownership of the in parcel and automatically deletes it after it 479 * is sent to the remote process. The output parcel is the result of the transaction. If the 480 * transaction has FLAG_ONEWAY, the out parcel will be empty. Otherwise, this will block until the 481 * remote process has processed the transaction, and the out parcel will contain the output data 482 * from transaction. 483 * 484 * This does not affect the ownership of binder. The out parcel's ownership is passed to the caller 485 * and must be released with AParcel_delete when finished reading. 486 * 487 * Available since API level 29. 488 * 489 * \param binder the binder object to transact on. 490 * \param code the implementation-specific code representing which transaction should be taken. 491 * \param in the implementation-specific input data to this transaction. 492 * \param out the implementation-specific output data to this transaction. 493 * \param flags possible flags to alter the way in which the transaction is conducted or 0. 494 * 495 * \return the result from the kernel or from the remote process. Usually, implementation-specific 496 * error codes are written to the output parcel, and the transaction code is reserved for kernel 497 * errors or error codes that have been repeated from subsequent transactions. 498 */ 499 binder_status_t AIBinder_transact(AIBinder* binder, transaction_code_t code, AParcel** in, 500 AParcel** out, binder_flags_t flags) __INTRODUCED_IN(29); 501 502 /** 503 * This does not take any ownership of the input binder, but it can be used to retrieve it if 504 * something else in some process still holds a reference to it. 505 * 506 * Available since API level 29. 507 * 508 * \param binder object to create a weak pointer to. 509 * 510 * \return object representing a weak pointer to binder (or null if binder is null). 511 */ 512 __attribute__((warn_unused_result)) AIBinder_Weak* AIBinder_Weak_new(AIBinder* binder) 513 __INTRODUCED_IN(29); 514 515 /** 516 * Deletes the weak reference. This will have no impact on the lifetime of the binder. 517 * 518 * Available since API level 29. 519 * 520 * \param weakBinder object created with AIBinder_Weak_new. 521 */ 522 void AIBinder_Weak_delete(AIBinder_Weak* weakBinder) __INTRODUCED_IN(29); 523 524 /** 525 * If promotion succeeds, result will have one strong refcount added to it. Otherwise, this returns 526 * null. 527 * 528 * Available since API level 29. 529 * 530 * \param weakBinder weak pointer to attempt retrieving the original object from. 531 * 532 * \return an AIBinder object with one refcount given to the caller or null. 533 */ 534 __attribute__((warn_unused_result)) AIBinder* AIBinder_Weak_promote(AIBinder_Weak* weakBinder) 535 __INTRODUCED_IN(29); 536 537 /** 538 * This function is executed on death receipt. See AIBinder_linkToDeath/AIBinder_unlinkToDeath. 539 * 540 * Available since API level 29. 541 * 542 * \param cookie the cookie passed to AIBinder_linkToDeath. 543 */ 544 typedef void (*AIBinder_DeathRecipient_onBinderDied)(void* cookie) __INTRODUCED_IN(29); 545 546 /** 547 * Creates a new binder death recipient. This can be attached to multiple different binder objects. 548 * 549 * Available since API level 29. 550 * 551 * \param onBinderDied the callback to call when this death recipient is invoked. 552 * 553 * \return the newly constructed object (or null if onBinderDied is null). 554 */ 555 __attribute__((warn_unused_result)) AIBinder_DeathRecipient* AIBinder_DeathRecipient_new( 556 AIBinder_DeathRecipient_onBinderDied onBinderDied) __INTRODUCED_IN(29); 557 558 /** 559 * Deletes a binder death recipient. It is not necessary to call AIBinder_unlinkToDeath before 560 * calling this as these will all be automatically unlinked. 561 * 562 * Available since API level 29. 563 * 564 * \param recipient the binder to delete (previously created with AIBinder_DeathRecipient_new). 565 */ 566 void AIBinder_DeathRecipient_delete(AIBinder_DeathRecipient* recipient) __INTRODUCED_IN(29); 567 568 #endif //__ANDROID_API__ >= 29 569 570 #if __ANDROID_API__ >= 30 571 572 /** 573 * Gets the extension registered with AIBinder_setExtension. 574 * 575 * See AIBinder_setExtension. 576 * 577 * Available since API level 30. 578 * 579 * \param binder the object to get the extension of. 580 * \param outExt the returned extension object. Will be null if there is no extension set or 581 * non-null with one strong ref count. 582 * 583 * \return error of getting the interface (may be a transaction error if this is 584 * remote binder). STATUS_UNEXPECTED_NULL if binder is null. 585 */ 586 binder_status_t AIBinder_getExtension(AIBinder* binder, AIBinder** outExt) __INTRODUCED_IN(30); 587 588 /** 589 * Gets the extension of a binder interface. This allows a downstream developer to add 590 * an extension to an interface without modifying its interface file. This should be 591 * called immediately when the object is created before it is passed to another thread. 592 * No thread safety is required. 593 * 594 * For instance, imagine if we have this interface: 595 * interface IFoo { void doFoo(); } 596 * 597 * A). Historical option that has proven to be BAD! Only the original 598 * author of an interface should change an interface. If someone 599 * downstream wants additional functionality, they should not ever 600 * change the interface or use this method. 601 * 602 * BAD TO DO: interface IFoo { BAD TO DO 603 * BAD TO DO: void doFoo(); BAD TO DO 604 * BAD TO DO: + void doBar(); // adding a method BAD TO DO 605 * BAD TO DO: } BAD TO DO 606 * 607 * B). Option that this method enables. 608 * Leave the original interface unchanged (do not change IFoo!). 609 * Instead, create a new interface in a downstream package: 610 * 611 * package com.<name>; // new functionality in a new package 612 * interface IBar { void doBar(); } 613 * 614 * When registering the interface, add: 615 * std::shared_ptr<MyFoo> foo = new MyFoo; // class in AOSP codebase 616 * std::shared_ptr<MyBar> bar = new MyBar; // custom extension class 617 * ... = AIBinder_setExtension(foo->asBinder().get(), bar->asBinder().get()); 618 * // handle error 619 * 620 * Then, clients of IFoo can get this extension: 621 * SpAIBinder binder = ...; 622 * std::shared_ptr<IFoo> foo = IFoo::fromBinder(binder); // handle if null 623 * SpAIBinder barBinder; 624 * ... = AIBinder_getExtension(barBinder.get()); 625 * // handle error 626 * std::shared_ptr<IBar> bar = IBar::fromBinder(barBinder); 627 * // type is checked with AIBinder_associateClass 628 * // if bar is null, then there is no extension or a different 629 * // type of extension 630 * 631 * Available since API level 30. 632 * 633 * \param binder the object to get the extension on. Must be local. 634 * \param ext the extension to set (binder will hold a strong reference to this) 635 * 636 * \return OK on success, STATUS_INVALID_OPERATION if binder is not local, STATUS_UNEXPECTED_NULL 637 * if either binder is null. 638 */ 639 binder_status_t AIBinder_setExtension(AIBinder* binder, AIBinder* ext) __INTRODUCED_IN(30); 640 641 #endif //__ANDROID_API__ >= 30 642 643 __END_DECLS 644 645 /** @} */ 646