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