NdkBinder

#include <binder_ibinder.h>

#include <binder_ibinder_jni.h>

#include <binder_parcel.h>

#include <binder_parcel_jni.h>

#include <binder_status.h>

Summary

Enumerations

Anonymous Enum 17{
  FLAG_ONEWAY = 0x01
}
enum
Anonymous Enum 18{
  FIRST_CALL_TRANSACTION = 0x00000001,
  LAST_CALL_TRANSACTION = 0x00ffffff
}
enum
Anonymous Enum 19{
  STATUS_OK = 0,
  STATUS_UNKNOWN_ERROR = (-2147483647 - 1),
  STATUS_NO_MEMORY = -ENOMEM,
  STATUS_INVALID_OPERATION = -ENOSYS,
  STATUS_BAD_VALUE = -EINVAL,
  STATUS_BAD_TYPE = (STATUS_UNKNOWN_ERROR + 1),
  STATUS_NAME_NOT_FOUND = -ENOENT,
  STATUS_PERMISSION_DENIED = -EPERM,
  STATUS_NO_INIT = -ENODEV,
  STATUS_ALREADY_EXISTS = -EEXIST,
  STATUS_DEAD_OBJECT = -EPIPE,
  STATUS_FAILED_TRANSACTION = (STATUS_UNKNOWN_ERROR + 2),
  STATUS_BAD_INDEX = -EOVERFLOW,
  STATUS_NOT_ENOUGH_DATA = -ENODATA,
  STATUS_WOULD_BLOCK = -EWOULDBLOCK,
  STATUS_TIMED_OUT = -ETIMEDOUT,
  STATUS_UNKNOWN_TRANSACTION = -EBADMSG,
  STATUS_FDS_NOT_ALLOWED = (STATUS_UNKNOWN_ERROR + 7),
  STATUS_UNEXPECTED_NULL = (STATUS_UNKNOWN_ERROR + 8)
}
enum
Low-level status types for use in binder.
Anonymous Enum 20{
  EX_NONE = 0,
  EX_SECURITY = -1,
  EX_BAD_PARCELABLE = -2,
  EX_ILLEGAL_ARGUMENT = -3,
  EX_NULL_POINTER = -4,
  EX_ILLEGAL_STATE = -5,
  EX_NETWORK_MAIN_THREAD = -6,
  EX_UNSUPPORTED_OPERATION = -7,
  EX_SERVICE_SPECIFIC = -8,
  EX_PARCELABLE = -9,
  EX_TRANSACTION_FAILED = -129
}
enum
Top level exceptions types for Android binder errors, mapping to Java exceptions.

Typedefs

AIBinder typedef
struct AIBinder
AIBinder typedef
struct AIBinder
AIBinder_Class typedef
struct AIBinder_Class
AIBinder_Class_onCreate)(void *args) typedef
void *(*
This is called whenever a new AIBinder object is needed of a specific class.
AIBinder_Class_onDestroy)(void *userData) typedef
void(*
This is called whenever an AIBinder object is no longer referenced and needs destroyed.
AIBinder_Class_onTransact)(AIBinder *binder, transaction_code_t code, const AParcel *in, AParcel *out) typedef
This is called whenever a transaction needs to be processed by a local implementation.
AIBinder_DeathRecipient typedef
struct AIBinder_DeathRecipient
AIBinder_DeathRecipient_onBinderDied)(void *cookie) typedef
void(*
This function is executed on death receipt.
AIBinder_DeathRecipient_onBinderUnlinked)(void *cookie) typedef
void(*
This function is intended for cleaning up the data in the provided cookie, and it is executed when the DeathRecipient is unlinked.
AIBinder_Weak typedef
struct AIBinder_Weak
AIBinder_onDump)(AIBinder *binder, int fd, const char **args, uint32_t numArgs) typedef
Dump information about an AIBinder (usually for debugging).
AParcel typedef
struct AParcel
AParcel_boolArrayAllocator)(void *arrayData, int32_t length) typedef
bool(*
This allocates an array of size 'length' inside of arrayData and returns whether or not there was a success.
AParcel_boolArrayGetter)(const void *arrayData, size_t index) typedef
bool(*
This is called to get the underlying data from an arrayData object at index.
AParcel_boolArraySetter)(void *arrayData, size_t index, bool value) typedef
void(*
This is called to set an underlying value in an arrayData object at index.
AParcel_byteArrayAllocator)(void *arrayData, int32_t length, int8_t **outBuffer) typedef
bool(*
This is called to get the underlying data from an arrayData object.
AParcel_charArrayAllocator)(void *arrayData, int32_t length, char16_t **outBuffer) typedef
bool(*
This is called to get the underlying data from an arrayData object.
AParcel_doubleArrayAllocator)(void *arrayData, int32_t length, double **outBuffer) typedef
bool(*
This is called to get the underlying data from an arrayData object.
AParcel_floatArrayAllocator)(void *arrayData, int32_t length, float **outBuffer) typedef
bool(*
This is called to get the underlying data from an arrayData object.
AParcel_int32ArrayAllocator)(void *arrayData, int32_t length, int32_t **outBuffer) typedef
bool(*
This is called to get the underlying data from an arrayData object.
AParcel_int64ArrayAllocator)(void *arrayData, int32_t length, int64_t **outBuffer) typedef
bool(*
This is called to get the underlying data from an arrayData object.
AParcel_parcelableArrayAllocator)(void *arrayData, int32_t length) typedef
bool(*
This is called to allocate an array of size 'length'.
AParcel_readParcelableElement)(const AParcel *parcel, void *arrayData, size_t index) typedef
This is called to set an underlying value in an arrayData object at index.
AParcel_stringAllocator)(void *stringData, int32_t length, char **buffer) typedef
bool(*
This is called to allocate a buffer for a C-style string (null-terminated).
AParcel_stringArrayAllocator)(void *arrayData, int32_t length) typedef
bool(*
This is called to allocate an array of size 'length'.
AParcel_stringArrayElementAllocator)(void *arrayData, size_t index, int32_t length, char **buffer) typedef
bool(*
This is called to allocate a string inside of an array that was allocated by an AParcel_stringArrayAllocator.
AParcel_stringArrayElementGetter)(const void *arrayData, size_t index, int32_t *outLength) typedef
const char *(*
This returns the length and buffer of an array at a specific index in an arrayData object.
AParcel_uint32ArrayAllocator)(void *arrayData, int32_t length, uint32_t **outBuffer) typedef
bool(*
This is called to get the underlying data from an arrayData object.
AParcel_uint64ArrayAllocator)(void *arrayData, int32_t length, uint64_t **outBuffer) typedef
bool(*
This is called to get the underlying data from an arrayData object.
AParcel_writeParcelableElement)(AParcel *parcel, const void *arrayData, size_t index) typedef
This is called to parcel the underlying data from an arrayData object at index.
AStatus typedef
struct AStatus
binder_exception_t typedef
int32_t
One of the EX_* enumerators.
binder_flags_t typedef
uint32_t
Flags for AIBinder_transact.
binder_status_t typedef
int32_t
One of the STATUS_* values.
transaction_code_t typedef
uint32_t
Codes for AIBinder_transact.

Functions

AIBinder_Class_define(const char *interfaceDescriptor, AIBinder_Class_onCreate onCreate, AIBinder_Class_onDestroy onDestroy, AIBinder_Class_onTransact onTransact)
AIBinder_Class *
This creates a new instance of a class of binders which can be instantiated.
AIBinder_Class_disableInterfaceTokenHeader(AIBinder_Class *clazz)
void
This tells users of this class not to use a transaction header.
AIBinder_Class_getDescriptor(const AIBinder_Class *clazz)
const char *
Retrieve the class descriptor for the class.
AIBinder_Class_setOnDump(AIBinder_Class *clazz, AIBinder_onDump onDump)
void
This sets the implementation of the dump method for a class.
AIBinder_DeathRecipient_delete(AIBinder_DeathRecipient *recipient)
void
Deletes a binder death recipient.
AIBinder_DeathRecipient_new(AIBinder_DeathRecipient_onBinderDied onBinderDied)
AIBinder_DeathRecipient *
Creates a new binder death recipient.
AIBinder_DeathRecipient_setOnUnlinked(AIBinder_DeathRecipient *recipient, AIBinder_DeathRecipient_onBinderUnlinked onUnlinked)
void
Set the callback to be called when this DeathRecipient is unlinked from a binder.
AIBinder_Weak_clone(const AIBinder_Weak *weak)
AIBinder_Weak *
Clone an AIBinder_Weak.
AIBinder_Weak_delete(AIBinder_Weak *weakBinder)
void
Deletes the weak reference.
AIBinder_Weak_lt(const AIBinder_Weak *lhs, const AIBinder_Weak *rhs)
bool
Whether AIBinder_Weak is less than another.
AIBinder_Weak_new(AIBinder *binder)
AIBinder_Weak *
This does not take any ownership of the input binder, but it can be used to retrieve it if something else in some process still holds a reference to it.
AIBinder_Weak_promote(AIBinder_Weak *weakBinder)
AIBinder *
If promotion succeeds, result will have one strong refcount added to it.
AIBinder_associateClass(AIBinder *binder, const AIBinder_Class *clazz)
bool
This sets the class of an AIBinder object.
AIBinder_debugGetRefCount(AIBinder *binder)
int32_t
For debugging only!
AIBinder_decStrong(AIBinder *binder)
void
This will delete the object and call onDestroy once the refcount reaches zero.
AIBinder_dump(AIBinder *binder, int fd, const char **args, uint32_t numArgs)
Built-in transaction for all binder objects.
AIBinder_fromJavaBinder(JNIEnv *env, jobject binder)
AIBinder *
Converts an android.os.IBinder object into an AIBinder* object.
AIBinder_getCallingPid()
pid_t
This returns the calling PID assuming that this thread is called from a thread that is processing a binder transaction (for instance, in the implementation of AIBinder_Class_onTransact).
AIBinder_getCallingUid()
uid_t
This returns the calling UID assuming that this thread is called from a thread that is processing a binder transaction (for instance, in the implementation of AIBinder_Class_onTransact).
AIBinder_getClass(AIBinder *binder)
const AIBinder_Class *
Returns the class that this binder was constructed with or associated with.
AIBinder_getExtension(AIBinder *binder, AIBinder **outExt)
Gets the extension registered with AIBinder_setExtension.
AIBinder_getUserData(AIBinder *binder)
void *
Value returned by onCreate for a local binder.
AIBinder_incStrong(AIBinder *binder)
void
This can only be called if a strong reference to this object already exists in process.
AIBinder_isAlive(const AIBinder *binder)
bool
If this binder is known to be alive.
AIBinder_isHandlingTransaction()
bool
Determine whether the current thread is currently executing an incoming transaction.
AIBinder_isRemote(const AIBinder *binder)
bool
If this is hosted in a process other than the current one.
AIBinder_linkToDeath(AIBinder *binder, AIBinder_DeathRecipient *recipient, void *cookie)
Registers for notifications that the associated binder is dead.
AIBinder_lt(const AIBinder *lhs, const AIBinder *rhs)
bool
Whether AIBinder is less than another.
AIBinder_new(const AIBinder_Class *clazz, void *args)
AIBinder *
Creates a new binder object of the appropriate class.
AIBinder_ping(AIBinder *binder)
Built-in transaction for all binder objects.
AIBinder_prepareTransaction(AIBinder *binder, AParcel **in)
A transaction is a series of calls to these functions which looks this.
AIBinder_setExtension(AIBinder *binder, AIBinder *ext)
Gets the extension of a binder interface.
AIBinder_toJavaBinder(JNIEnv *env, AIBinder *binder)
jobject
Converts an AIBinder* object into an android.os.IBinder object.
AIBinder_transact(AIBinder *binder, transaction_code_t code, AParcel **in, AParcel **out, binder_flags_t flags)
Transact using a parcel created from AIBinder_prepareTransaction.
AIBinder_unlinkToDeath(AIBinder *binder, AIBinder_DeathRecipient *recipient, void *cookie)
Stops registration for the associated binder dying.
AParcel_appendFrom(const AParcel *from, AParcel *to, int32_t start, int32_t size)
Copy the data of a parcel to other parcel.
AParcel_create()
AParcel *
Creates a parcel.
AParcel_delete(AParcel *parcel)
void
Cleans up a parcel.
AParcel_fromJavaParcel(JNIEnv *env, jobject parcel)
AParcel *
Converts an android.os.Parcel object into an AParcel* object.
AParcel_getDataPosition(const AParcel *parcel)
int32_t
Gets the current position within the parcel.
AParcel_getDataSize(const AParcel *parcel)
int32_t
Gets the size of the parcel.
AParcel_marshal(const AParcel *parcel, uint8_t *buffer, size_t start, size_t len)
Marshals the raw bytes of the Parcel to a buffer.
AParcel_readBool(const AParcel *parcel, bool *value)
Reads into bool value from the next location in a non-null parcel.
AParcel_readBoolArray(const AParcel *parcel, void *arrayData, AParcel_boolArrayAllocator allocator, AParcel_boolArraySetter setter)
Reads an array of bool from the next location in a non-null parcel.
AParcel_readByte(const AParcel *parcel, int8_t *value)
Reads into int8_t value from the next location in a non-null parcel.
AParcel_readByteArray(const AParcel *parcel, void *arrayData, AParcel_byteArrayAllocator allocator)
Reads an array of int8_t from the next location in a non-null parcel.
AParcel_readChar(const AParcel *parcel, char16_t *value)
Reads into char16_t value from the next location in a non-null parcel.
AParcel_readCharArray(const AParcel *parcel, void *arrayData, AParcel_charArrayAllocator allocator)
Reads an array of char16_t from the next location in a non-null parcel.
AParcel_readDouble(const AParcel *parcel, double *value)
Reads into double value from the next location in a non-null parcel.
AParcel_readDoubleArray(const AParcel *parcel, void *arrayData, AParcel_doubleArrayAllocator allocator)
Reads an array of double from the next location in a non-null parcel.
AParcel_readFloat(const AParcel *parcel, float *value)
Reads into float value from the next location in a non-null parcel.
AParcel_readFloatArray(const AParcel *parcel, void *arrayData, AParcel_floatArrayAllocator allocator)
Reads an array of float from the next location in a non-null parcel.
AParcel_readInt32(const AParcel *parcel, int32_t *value)
Reads into int32_t value from the next location in a non-null parcel.
AParcel_readInt32Array(const AParcel *parcel, void *arrayData, AParcel_int32ArrayAllocator allocator)
Reads an array of int32_t from the next location in a non-null parcel.
AParcel_readInt64(const AParcel *parcel, int64_t *value)
Reads into int64_t value from the next location in a non-null parcel.
AParcel_readInt64Array(const AParcel *parcel, void *arrayData, AParcel_int64ArrayAllocator allocator)
Reads an array of int64_t from the next location in a non-null parcel.
AParcel_readParcelFileDescriptor(const AParcel *parcel, int *fd)
Reads an int from the next location in a non-null parcel.
AParcel_readParcelableArray(const AParcel *parcel, void *arrayData, AParcel_parcelableArrayAllocator allocator, AParcel_readParcelableElement elementReader)
Reads an array of parcelables (user-defined types) from the next location in a non-null parcel.
AParcel_readStatusHeader(const AParcel *parcel, AStatus **status)
Reads an AStatus from the next location in a non-null parcel.
AParcel_readString(const AParcel *parcel, void *stringData, AParcel_stringAllocator allocator)
Reads and allocates utf-8 string value from the next location in a non-null parcel.
AParcel_readStringArray(const AParcel *parcel, void *arrayData, AParcel_stringArrayAllocator allocator, AParcel_stringArrayElementAllocator elementAllocator)
Reads and allocates utf-8 string array value from the next location in a non-null parcel.
AParcel_readStrongBinder(const AParcel *parcel, AIBinder **binder)
Reads an AIBinder from the next location in a non-null parcel.
AParcel_readUint32(const AParcel *parcel, uint32_t *value)
Reads into uint32_t value from the next location in a non-null parcel.
AParcel_readUint32Array(const AParcel *parcel, void *arrayData, AParcel_uint32ArrayAllocator allocator)
Reads an array of uint32_t from the next location in a non-null parcel.
AParcel_readUint64(const AParcel *parcel, uint64_t *value)
Reads into uint64_t value from the next location in a non-null parcel.
AParcel_readUint64Array(const AParcel *parcel, void *arrayData, AParcel_uint64ArrayAllocator allocator)
Reads an array of uint64_t from the next location in a non-null parcel.
AParcel_reset(AParcel *parcel)
Reset the parcel to the initial status.
AParcel_setDataPosition(const AParcel *parcel, int32_t position)
Sets the position within the parcel.
AParcel_unmarshal(AParcel *parcel, const uint8_t *buffer, size_t len)
Set the data in the parcel to the raw bytes from the buffer.
AParcel_writeBool(AParcel *parcel, bool value)
Writes bool value to the next location in a non-null parcel.
AParcel_writeBoolArray(AParcel *parcel, const void *arrayData, int32_t length, AParcel_boolArrayGetter getter)
Writes an array of bool to the next location in a non-null parcel.
AParcel_writeByte(AParcel *parcel, int8_t value)
Writes int8_t value to the next location in a non-null parcel.
AParcel_writeByteArray(AParcel *parcel, const int8_t *arrayData, int32_t length)
Writes an array of int8_t to the next location in a non-null parcel.
AParcel_writeChar(AParcel *parcel, char16_t value)
Writes char16_t value to the next location in a non-null parcel.
AParcel_writeCharArray(AParcel *parcel, const char16_t *arrayData, int32_t length)
Writes an array of char16_t to the next location in a non-null parcel.
AParcel_writeDouble(AParcel *parcel, double value)
Writes double value to the next location in a non-null parcel.
AParcel_writeDoubleArray(AParcel *parcel, const double *arrayData, int32_t length)
Writes an array of double to the next location in a non-null parcel.
AParcel_writeFloat(AParcel *parcel, float value)
Writes float value to the next location in a non-null parcel.
AParcel_writeFloatArray(AParcel *parcel, const float *arrayData, int32_t length)
Writes an array of float to the next location in a non-null parcel.
AParcel_writeInt32(AParcel *parcel, int32_t value)
Writes int32_t value to the next location in a non-null parcel.
AParcel_writeInt32Array(AParcel *parcel, const int32_t *arrayData, int32_t length)
Writes an array of int32_t to the next location in a non-null parcel.
AParcel_writeInt64(AParcel *parcel, int64_t value)
Writes int64_t value to the next location in a non-null parcel.
AParcel_writeInt64Array(AParcel *parcel, const int64_t *arrayData, int32_t length)
Writes an array of int64_t to the next location in a non-null parcel.
AParcel_writeParcelFileDescriptor(AParcel *parcel, int fd)
Writes a file descriptor to the next location in a non-null parcel.
AParcel_writeParcelableArray(AParcel *parcel, const void *arrayData, int32_t length, AParcel_writeParcelableElement elementWriter)
Writes an array of parcelables (user-defined types) to the next location in a non-null parcel.
AParcel_writeStatusHeader(AParcel *parcel, const AStatus *status)
Writes an AStatus object to the next location in a non-null parcel.
AParcel_writeString(AParcel *parcel, const char *string, int32_t length)
Writes utf-8 string value to the next location in a non-null parcel.
AParcel_writeStringArray(AParcel *parcel, const void *arrayData, int32_t length, AParcel_stringArrayElementGetter getter)
Writes utf-8 string array data to the next location in a non-null parcel.
AParcel_writeStrongBinder(AParcel *parcel, AIBinder *binder)
Writes an AIBinder to the next location in a non-null parcel.
AParcel_writeUint32(AParcel *parcel, uint32_t value)
Writes uint32_t value to the next location in a non-null parcel.
AParcel_writeUint32Array(AParcel *parcel, const uint32_t *arrayData, int32_t length)
Writes an array of uint32_t to the next location in a non-null parcel.
AParcel_writeUint64(AParcel *parcel, uint64_t value)
Writes uint64_t value to the next location in a non-null parcel.
AParcel_writeUint64Array(AParcel *parcel, const uint64_t *arrayData, int32_t length)
Writes an array of uint64_t to the next location in a non-null parcel.
AStatus_delete(AStatus *status)
void
Deletes memory associated with the status instance.
AStatus_deleteDescription(const char *description)
void
Delete description.
AStatus_fromExceptionCode(binder_exception_t exception)
AStatus *
New status with exception code.
AStatus_fromExceptionCodeWithMessage(binder_exception_t exception, const char *message)
AStatus *
New status with exception code and message.
AStatus_fromServiceSpecificError(int32_t serviceSpecific)
AStatus *
New status with a service speciic error.
AStatus_fromServiceSpecificErrorWithMessage(int32_t serviceSpecific, const char *message)
AStatus *
New status with a service specific error and message.
AStatus_fromStatus(binder_status_t status)
AStatus *
New status with binder_status_t.
AStatus_getDescription(const AStatus *status)
const char *
Get human-readable description for debugging.
AStatus_getExceptionCode(const AStatus *status)
The exception that this status object represents.
AStatus_getMessage(const AStatus *status)
const char *
If there is a message associated with this status, this will return that message.
AStatus_getServiceSpecificError(const AStatus *status)
int32_t
The service specific error if this object represents one.
AStatus_getStatus(const AStatus *status)
The status if this object represents one.
AStatus_isOk(const AStatus *status)
bool
Whether this object represents a successful transaction.
AStatus_newOk()
AStatus *
New status which is considered a success.

Enumerations

Anonymous Enum 17

 Anonymous Enum 17
Properties
FLAG_ONEWAY

The transaction will be dispatched and then returned to the caller.

The outgoing process cannot block a call made by this, and execution of the call will not be waited on. An error can still be returned if the call is unable to be processed by the binder driver. All oneway calls are guaranteed to be ordered if they are sent on the same AIBinder object.

Anonymous Enum 18

 Anonymous Enum 18
Properties
FIRST_CALL_TRANSACTION

The first transaction code available for user commands (inclusive).

LAST_CALL_TRANSACTION

The last transaction code available for user commands (inclusive).

Anonymous Enum 20

 Anonymous Enum 20

Top level exceptions types for Android binder errors, mapping to Java exceptions.

Also see Parcel.java.

Properties
EX_BAD_PARCELABLE
EX_ILLEGAL_ARGUMENT
EX_ILLEGAL_STATE
EX_NETWORK_MAIN_THREAD
EX_NONE
EX_NULL_POINTER
EX_PARCELABLE
EX_SECURITY
EX_SERVICE_SPECIFIC
EX_TRANSACTION_FAILED

This is special, and indicates to native binder proxies that the transaction has failed at a low level.

EX_UNSUPPORTED_OPERATION

Typedefs

AIBinder

struct AIBinder AIBinder

AIBinder

struct AIBinder AIBinder

AIBinder_Class

struct AIBinder_Class AIBinder_Class

AIBinder_Class_onCreate

void *(* AIBinder_Class_onCreate)(void *args)

This is called whenever a new AIBinder object is needed of a specific class.

Details
Parameters
args
these can be used to construct a new class. These are passed from AIBinder_new.
Returns
this is the userdata representing the class. It can be retrieved using AIBinder_getUserData.

AIBinder_Class_onDestroy

void(* AIBinder_Class_onDestroy)(void *userData)

This is called whenever an AIBinder object is no longer referenced and needs destroyed.

Typically, this just deletes whatever the implementation is.

Details
Parameters
userData
this is the same object returned by AIBinder_Class_onCreate

AIBinder_Class_onTransact

binder_status_t(* AIBinder_Class_onTransact)(AIBinder *binder, transaction_code_t code, const AParcel *in, AParcel *out)

This is called whenever a transaction needs to be processed by a local implementation.

This method will be called after the equivalent of android.os.Parcel::enforceInterface is called. That is, the interface descriptor associated with the AIBinder_Class descriptor will already be checked.

Details
Parameters
binder
the object being transacted on.
code
implementation-specific code representing which transaction should be taken.
in
the implementation-specific input data to this transaction.
out
the implementation-specific output data to this transaction.
Returns
the implementation-specific output code. This may be forwarded from another service, the result of a parcel read or write, or another error as is applicable to the specific implementation. Usually, implementation-specific error codes are written to the output parcel, and the transaction code is reserved for kernel errors or error codes that have been repeated from subsequent transactions.

AIBinder_DeathRecipient

struct AIBinder_DeathRecipient AIBinder_DeathRecipient

AIBinder_DeathRecipient_onBinderDied

void(* AIBinder_DeathRecipient_onBinderDied)(void *cookie)

This function is executed on death receipt.

See AIBinder_linkToDeath/AIBinder_unlinkToDeath.

Available since API level 29.

Details
Parameters
cookie
the cookie passed to AIBinder_linkToDeath.

AIBinder_DeathRecipient_onBinderUnlinked

void(* AIBinder_DeathRecipient_onBinderUnlinked)(void *cookie)

This function is intended for cleaning up the data in the provided cookie, and it is executed when the DeathRecipient is unlinked.

When the DeathRecipient is unlinked due to a death receipt, this method is called after the call to onBinderDied.

This method is called once for each binder that is unlinked. Hence, if the same cookie is passed to multiple binders, then the caller is responsible for reference counting the cookie.

See also AIBinder_linkToDeath/AIBinder_unlinkToDeath.

WARNING: Make sure the lifetime of this cookie is long enough. If it is dynamically allocated, it should be deleted with AIBinder_DeathRecipient_setOnUnlinked.

Available since API level 33.

Details
Parameters
cookie
the cookie passed to AIBinder_linkToDeath.

AIBinder_Weak

struct AIBinder_Weak AIBinder_Weak

AIBinder_onDump

binder_status_t(* AIBinder_onDump)(AIBinder *binder, int fd, const char **args, uint32_t numArgs)

Dump information about an AIBinder (usually for debugging).

When no arguments are provided, a brief overview of the interview should be given.

Details
Parameters
binder
interface being dumped
fd
file descriptor to be dumped to, should be flushed, ownership is not passed.
args
array of null-terminated strings for dump (may be null if numArgs is 0)
numArgs
number of args to be sent
Returns
binder_status_t result of transaction (if remote, for instance)

AParcel

struct AParcel AParcel

AParcel_boolArrayAllocator

bool(* AParcel_boolArrayAllocator)(void *arrayData, int32_t length)

This allocates an array of size 'length' inside of arrayData and returns whether or not there was a success.

If length is -1, then this should allocate some representation of a null array.

See also AParcel_readBoolArray

Details
Parameters
arrayData
some external representation of an array of bool.
length
the length to allocate arrayData to (or -1 if this represents a null array).
Returns
whether the allocation succeeded.

AParcel_boolArrayGetter

bool(* AParcel_boolArrayGetter)(const void *arrayData, size_t index)

This is called to get the underlying data from an arrayData object at index.

See also AParcel_writeBoolArray

Details
Parameters
arrayData
some external representation of an array of bool.
index
the index of the value to be retrieved.
Returns
the value of the array at index index.

AParcel_boolArraySetter

void(* AParcel_boolArraySetter)(void *arrayData, size_t index, bool value)

This is called to set an underlying value in an arrayData object at index.

See also AParcel_readBoolArray

Details
Parameters
arrayData
some external representation of an array of bool.
index
the index of the value to be set.
value
the value to set at index index.

AParcel_byteArrayAllocator

bool(* AParcel_byteArrayAllocator)(void *arrayData, int32_t length, int8_t **outBuffer)

This is called to get the underlying data from an arrayData object.

The implementation of this function should allocate a contiguous array of size 'length' and return that underlying buffer to be filled out. If there is an error or length is 0, null may be returned. If length is -1, this should allocate some representation of a null array.

See also AParcel_readByteArray

Details
Parameters
arrayData
some external representation of an array of int8_t.
length
the length to allocate arrayData to.
outBuffer
a buffer of int8_t of size 'length' (if length is >= 0, if length is 0, this may be nullptr).
Returns
whether or not the allocation was successful (or whether a null array is represented when length is -1).

AParcel_charArrayAllocator

bool(* AParcel_charArrayAllocator)(void *arrayData, int32_t length, char16_t **outBuffer)

This is called to get the underlying data from an arrayData object.

The implementation of this function should allocate a contiguous array of size 'length' and return that underlying buffer to be filled out. If there is an error or length is 0, null may be returned. If length is -1, this should allocate some representation of a null array.

See also AParcel_readCharArray

Details
Parameters
arrayData
some external representation of an array of char16_t.
length
the length to allocate arrayData to.
outBuffer
a buffer of char16_t of size 'length' (if length is >= 0, if length is 0, this may be nullptr).
Returns
whether or not the allocation was successful (or whether a null array is represented when length is -1).

AParcel_doubleArrayAllocator

bool(* AParcel_doubleArrayAllocator)(void *arrayData, int32_t length, double **outBuffer)

This is called to get the underlying data from an arrayData object.

The implementation of this function should allocate a contiguous array of size 'length' and return that underlying buffer to be filled out. If there is an error or length is 0, null may be returned. If length is -1, this should allocate some representation of a null array.

See also AParcel_readDoubleArray

Details
Parameters
arrayData
some external representation of an array of double.
length
the length to allocate arrayData to.
outBuffer
a buffer of double of size 'length' (if length is >= 0, if length is 0, this may be nullptr).
Returns
whether or not the allocation was successful (or whether a null array is represented when length is -1).

AParcel_floatArrayAllocator

bool(* AParcel_floatArrayAllocator)(void *arrayData, int32_t length, float **outBuffer)

This is called to get the underlying data from an arrayData object.

The implementation of this function should allocate a contiguous array of size 'length' and return that underlying buffer to be filled out. If there is an error or length is 0, null may be returned. If length is -1, this should allocate some representation of a null array.

See also AParcel_readFloatArray

Details
Parameters
arrayData
some external representation of an array of float.
length
the length to allocate arrayData to.
outBuffer
a buffer of float of size 'length' (if length is >= 0, if length is 0, this may be nullptr).
Returns
whether or not the allocation was successful (or whether a null array is represented when length is -1).

AParcel_int32ArrayAllocator

bool(* AParcel_int32ArrayAllocator)(void *arrayData, int32_t length, int32_t **outBuffer)

This is called to get the underlying data from an arrayData object.

The implementation of this function should allocate a contiguous array of size 'length' and return that underlying buffer to be filled out. If there is an error or length is 0, null may be returned. If length is -1, this should allocate some representation of a null array.

See also AParcel_readInt32Array

Details
Parameters
arrayData
some external representation of an array of int32_t.
length
the length to allocate arrayData to.
outBuffer
a buffer of int32_t of size 'length' (if length is >= 0, if length is 0, this may be nullptr).
Returns
whether or not the allocation was successful (or whether a null array is represented when length is -1).

AParcel_int64ArrayAllocator

bool(* AParcel_int64ArrayAllocator)(void *arrayData, int32_t length, int64_t **outBuffer)

This is called to get the underlying data from an arrayData object.

The implementation of this function should allocate a contiguous array of size 'length' and return that underlying buffer to be filled out. If there is an error or length is 0, null may be returned. If length is -1, this should allocate some representation of a null array.

See also AParcel_readInt64Array

Details
Parameters
arrayData
some external representation of an array of int64_t.
length
the length to allocate arrayData to.
outBuffer
a buffer of int64_t of size 'length' (if length is >= 0, if length is 0, this may be nullptr).
Returns
whether or not the allocation was successful (or whether a null array is represented when length is -1).

AParcel_parcelableArrayAllocator

bool(* AParcel_parcelableArrayAllocator)(void *arrayData, int32_t length)

This is called to allocate an array of size 'length'.

If length is -1, then a 'null' array (or equivalent) should be created.

See also AParcel_readParcelableArray

Details
Parameters
arrayData
some external representation of an array
length
the length to allocate this array to
Returns
true if allocation succeeded. If length is -1, a true return here means that a 'null' value (or equivalent) was successfully stored.

AParcel_readParcelableElement

binder_status_t(* AParcel_readParcelableElement)(const AParcel *parcel, void *arrayData, size_t index)

This is called to set an underlying value in an arrayData object at index.

See also AParcel_readParcelableArray

Details
Parameters
parcel
parcel to read the parcelable from
arrayData
some external representation of an array of parcelables (a user-defined type).
index
the index of the value to be set.
Returns
status (usually returned from other parceling functions). STATUS_OK for success.

AParcel_stringAllocator

bool(* AParcel_stringAllocator)(void *stringData, int32_t length, char **buffer)

This is called to allocate a buffer for a C-style string (null-terminated).

The returned buffer should be at least length bytes. This includes space for a null terminator. For a string, length will always be strictly less than or equal to the maximum size that can be held in a size_t and will always be greater than 0. However, if a 'null' string is being read, length will be -1.

See also AParcel_readString.

If allocation fails, null should be returned.

Details
Parameters
stringData
some external representation of a string
length
the length of the buffer needed to fill (including the null-terminator)
buffer
a buffer of size 'length' or null if allocation failed.
Returns
true if the allocation succeeded, false otherwise. If length is -1, a true return here means that a 'null' value (or equivalent) was successfully stored.

AParcel_stringArrayAllocator

bool(* AParcel_stringArrayAllocator)(void *arrayData, int32_t length)

This is called to allocate an array of size 'length'.

If length is -1, then a 'null' array (or equivalent) should be created.

See also AParcel_readStringArray

Details
Parameters
arrayData
some external representation of an array
length
the length to allocate this array to
Returns
true if allocation succeeded. If length is -1, a true return here means that a 'null' value (or equivalent) was successfully stored.

AParcel_stringArrayElementAllocator

bool(* AParcel_stringArrayElementAllocator)(void *arrayData, size_t index, int32_t length, char **buffer)

This is called to allocate a string inside of an array that was allocated by an AParcel_stringArrayAllocator.

The index returned will always be within the range [0, length of arrayData). The returned buffer should be at least length bytes. This includes space for a null-terminator. For a string, length will always be strictly less than or equal to the maximum size that can be held in a size_t and will always be greater than 0. However, if a 'null' string is being read, length will be -1.

See also AParcel_readStringArray

Details
Parameters
arrayData
some external representation of an array.
index
the index at which a string should be allocated.
length
the length of the string to be allocated at this index. See also AParcel_stringAllocator. This includes the length required for a null-terminator.
buffer
a buffer of size 'length' or null if allocation failed.
Returns
true if the allocation succeeded, false otherwise. If length is -1, a true return here means that a 'null' value (or equivalent) was successfully stored.

AParcel_stringArrayElementGetter

const char *(* AParcel_stringArrayElementGetter)(const void *arrayData, size_t index, int32_t *outLength)

This returns the length and buffer of an array at a specific index in an arrayData object.

See also AParcel_writeStringArray

Details
Parameters
arrayData
some external representation of an array.
index
the index at which a string should be allocated.
outLength
an out parameter for the length of the string at the specified index. This should not include the length for a null-terminator if there is one. If the object at this index is 'null', then this should be set to -1.
a
buffer of size outLength or more representing the string at the provided index. This is not required to be null-terminated. If the object at index is null, then this should be null.

AParcel_uint32ArrayAllocator

bool(* AParcel_uint32ArrayAllocator)(void *arrayData, int32_t length, uint32_t **outBuffer)

This is called to get the underlying data from an arrayData object.

The implementation of this function should allocate a contiguous array of size 'length' and return that underlying buffer to be filled out. If there is an error or length is 0, null may be returned. If length is -1, this should allocate some representation of a null array.

See also AParcel_readUint32Array

Details
Parameters
arrayData
some external representation of an array of uint32_t.
length
the length to allocate arrayData to.
outBuffer
a buffer of uint32_t of size 'length' (if length is >= 0, if length is 0, this may be nullptr).
Returns
whether or not the allocation was successful (or whether a null array is represented when length is -1).

AParcel_uint64ArrayAllocator

bool(* AParcel_uint64ArrayAllocator)(void *arrayData, int32_t length, uint64_t **outBuffer)

This is called to get the underlying data from an arrayData object.

The implementation of this function should allocate a contiguous array of size 'length' and return that underlying buffer to be filled out. If there is an error or length is 0, null may be returned. If length is -1, this should allocate some representation of a null array.

See also AParcel_readUint64Array

Details
Parameters
arrayData
some external representation of an array of uint64_t.
length
the length to allocate arrayData to.
outBuffer
a buffer of uint64_t of size 'length' (if length is >= 0, if length is 0, this may be nullptr).
Returns
whether or not the allocation was successful (or whether a null array is represented when length is -1).

AParcel_writeParcelableElement

binder_status_t(* AParcel_writeParcelableElement)(AParcel *parcel, const void *arrayData, size_t index)

This is called to parcel the underlying data from an arrayData object at index.

See also AParcel_writeParcelableArray

Details
Parameters
parcel
parcel to write the parcelable to
arrayData
some external representation of an array of parcelables (a user-defined type).
index
the index of the value to be retrieved.
Returns
status (usually returned from other parceling functions). STATUS_OK for success.

AStatus

struct AStatus AStatus

binder_exception_t

int32_t binder_exception_t

One of the EX_* enumerators.

All unrecognized values are coerced into EX_TRANSACTION_FAILED.

These exceptions values are used by the SDK for parcelables. Also see Parcel.java.

binder_flags_t

uint32_t binder_flags_t

Flags for AIBinder_transact.

binder_status_t

int32_t binder_status_t

One of the STATUS_* values.

All unrecognized values are coerced into STATUS_UNKNOWN_ERROR.

transaction_code_t

uint32_t transaction_code_t

Codes for AIBinder_transact.

This defines the range of codes available for usage. Other codes are used or reserved by the Android system.

Functions

AIBinder_Class_define

AIBinder_Class * AIBinder_Class_define(
  const char *interfaceDescriptor,
  AIBinder_Class_onCreate onCreate,
  AIBinder_Class_onDestroy onDestroy,
  AIBinder_Class_onTransact onTransact
)

This creates a new instance of a class of binders which can be instantiated.

This is called one time during library initialization and cleaned up when the process exits or execs.

None of these parameters can be null.

Available since API level 29.

Details
Parameters
interfaceDescriptor
this is a unique identifier for the class. This is used internally for validity checks on transactions. This should be utf-8.
onCreate
see AIBinder_Class_onCreate.
onDestroy
see AIBinder_Class_onDestroy.
onTransact
see AIBinder_Class_onTransact.
Returns
the class object representing these parameters or null on error.

AIBinder_Class_disableInterfaceTokenHeader

void AIBinder_Class_disableInterfaceTokenHeader(
  AIBinder_Class *clazz
)

This tells users of this class not to use a transaction header.

By default, libbinder_ndk users read/write transaction headers implicitly (in the SDK, this must be manually written by android.os.Parcel::writeInterfaceToken, and it is read/checked with android.os.Parcel::enforceInterface). This method is provided in order to talk to legacy code which does not write an interface token. When this is disabled, type safety is reduced, so you must have a separate way of determining the binder you are talking to is the right type. Must be called before any instance of the class is created.

Available since API level 33.

WARNING: this API interacts badly with linkernamespaces. For correct behavior, you must use it on all instances of a class in the same process which share the same interface descriptor. In general, it is recommended you do not use this API, because it is disabling type safety.

Details
Parameters
clazz
class to disable interface header on.

AIBinder_Class_getDescriptor

const char * AIBinder_Class_getDescriptor(
  const AIBinder_Class *clazz
)

Retrieve the class descriptor for the class.

Available since API level 31.

Details
Parameters
clazz
the class to fetch the descriptor from
Returns
the class descriptor string. This pointer will never be null; a descriptor is required to define a class. The pointer is owned by the class and will remain valid as long as the class does. For a local class, this will be the same value (not necessarily pointer equal) as is passed into AIBinder_Class_define. Format is utf-8.

AIBinder_Class_setOnDump

void AIBinder_Class_setOnDump(
  AIBinder_Class *clazz,
  AIBinder_onDump onDump
)

This sets the implementation of the dump method for a class.

If this isn't set, nothing will be dumped when dump is called (for instance with android.os.Binder::dump). Must be called before any instance of the class is created.

Available since API level 29.

Details
Parameters
clazz
class which should use this dump function
onDump
function to call when an instance of this binder class is being dumped.

AIBinder_DeathRecipient_delete

void AIBinder_DeathRecipient_delete(
  AIBinder_DeathRecipient *recipient
)

Deletes a binder death recipient.

It is not necessary to call AIBinder_unlinkToDeath before calling this as these will all be automatically unlinked.

Be aware that it is not safe to immediately deallocate the cookie when this call returns. If you need to clean up the cookie, you should do so in the onUnlinked callback, which can be set using AIBinder_DeathRecipient_setOnUnlinked.

Available since API level 29.

Details
Parameters
recipient
the binder to delete (previously created with AIBinder_DeathRecipient_new).

AIBinder_DeathRecipient_new

AIBinder_DeathRecipient * AIBinder_DeathRecipient_new(
  AIBinder_DeathRecipient_onBinderDied onBinderDied
)

Creates a new binder death recipient.

This can be attached to multiple different binder objects.

Available since API level 29.

WARNING: Make sure the lifetime of this cookie is long enough. If it is dynamically allocated, it should be deleted with AIBinder_DeathRecipient_setOnUnlinked.

Details
Parameters
onBinderDied
the callback to call when this death recipient is invoked.
Returns
the newly constructed object (or null if onBinderDied is null).

AIBinder_DeathRecipient_setOnUnlinked

void AIBinder_DeathRecipient_setOnUnlinked(
  AIBinder_DeathRecipient *recipient,
  AIBinder_DeathRecipient_onBinderUnlinked onUnlinked
)

Set the callback to be called when this DeathRecipient is unlinked from a binder.

The callback is called in the following situations:

  1. If the binder died, shortly after the call to onBinderDied.
  2. If the binder is explicitly unlinked with AIBinder_unlinkToDeath or AIBinder_DeathRecipient_delete, after any pending onBinderDied calls finish.
  3. During or shortly after the AIBinder_linkToDeath call if it returns an error.

It is guaranteed that the callback is called exactly once for each call to linkToDeath unless the process is aborted before the binder is unlinked.

Be aware that when the binder is explicitly unlinked, it is not guaranteed that onUnlinked has been called before the call to AIBinder_unlinkToDeath or AIBinder_DeathRecipient_delete returns. For example, if the binder dies concurrently with a call to AIBinder_unlinkToDeath, the binder is not unlinked until after the death notification is delivered, even if AIBinder_unlinkToDeath returns before that happens.

This method should be called before linking the DeathRecipient to a binder because the function pointer is cached. If you change it after linking to a binder, it is unspecified whether the old binder will call the old or new onUnlinked callback.

The onUnlinked argument may be null. In this case, no notification is given when the binder is unlinked.

Available since API level 33.

Details
Parameters
recipient
the DeathRecipient to set the onUnlinked callback for.
onUnlinked
the callback to call when a binder is unlinked from recipient.

AIBinder_Weak_clone

AIBinder_Weak * AIBinder_Weak_clone(
  const AIBinder_Weak *weak
)

Clone an AIBinder_Weak.

Useful because even if a weak binder promotes to a null value, after further binder transactions, it may no longer promote to a null value.

Available since API level 31.

Details
Parameters
weak
Object to clone
Returns
clone of the input parameter. This must be deleted with AIBinder_Weak_delete. Null if weak input parameter is also null.

AIBinder_Weak_delete

void AIBinder_Weak_delete(
  AIBinder_Weak *weakBinder
)

Deletes the weak reference.

This will have no impact on the lifetime of the binder.

Available since API level 29.

Details
Parameters
weakBinder
object created with AIBinder_Weak_new.

AIBinder_Weak_lt

bool AIBinder_Weak_lt(
  const AIBinder_Weak *lhs,
  const AIBinder_Weak *rhs
)

Whether AIBinder_Weak is less than another.

This provides a per-process-unique total ordering of binders which is exactly the same as AIBinder_lt. Similarly, a null AIBinder_Weak* is considered to be ordered before all other weak references.

This function correctly distinguishes binders even if one is deallocated. So, for instance, an AIBinder_Weak* entry representing a deleted binder will never compare as equal to an AIBinder_Weak* entry which represents a different allocation of a binder, even if the two binders were originally allocated at the same address. That is:

AIBinder* a = ...; // imagine this has address 0x8
AIBinder_Weak* bWeak = AIBinder_Weak_new(a);
AIBinder_decStrong(a); // a may be deleted, if this is the last reference
AIBinder* b = ...; // imagine this has address 0x8 (same address as b)
AIBinder_Weak* bWeak = AIBinder_Weak_new(b);

Then when a/b are compared with other binders, their order will be preserved, and it will either be the case that AIBinder_Weak_lt(aWeak, bWeak) OR AIBinder_Weak_lt(bWeak, aWeak), but not both.

Unlike AIBinder*, the AIBinder_Weak* addresses themselves have nothing to do with the underlying binder.

Available since API level 31.

Details
Parameters
lhs
comparison object
rhs
comparison object
Returns
whether "lhs < rhs" is true

AIBinder_Weak_new

AIBinder_Weak * AIBinder_Weak_new(
  AIBinder *binder
)

This does not take any ownership of the input binder, but it can be used to retrieve it if something else in some process still holds a reference to it.

Available since API level 29.

Details
Parameters
binder
object to create a weak pointer to.
Returns
object representing a weak pointer to binder (or null if binder is null).

AIBinder_Weak_promote

AIBinder * AIBinder_Weak_promote(
  AIBinder_Weak *weakBinder
)

If promotion succeeds, result will have one strong refcount added to it.

Otherwise, this returns null.

Available since API level 29.

Details
Parameters
weakBinder
weak pointer to attempt retrieving the original object from.
Returns
an AIBinder object with one refcount given to the caller or null.

AIBinder_associateClass

bool AIBinder_associateClass(
  AIBinder *binder,
  const AIBinder_Class *clazz
)

This sets the class of an AIBinder object.

This checks to make sure the remote object is of the expected class. A class must be set in order to use transactions on an AIBinder object. However, if an object is just intended to be passed through to another process or used as a handle this need not be called.

This returns true if the class association succeeds. If it fails, no change is made to the binder object.

Warning: this may fail if the binder is dead.

Available since API level 29.

Details
Parameters
binder
the object to attach the class to.
clazz
the clazz to attach to binder.
Returns
true if the binder has the class clazz and if the association was successful.

AIBinder_debugGetRefCount

int32_t AIBinder_debugGetRefCount(
  AIBinder *binder
)

For debugging only!

Available since API level 29.

Details
Parameters
binder
the binder object to retrieve the refcount of.
Returns
the number of strong-refs on this binder in this process. If binder is null, this will be -1.

AIBinder_decStrong

void AIBinder_decStrong(
  AIBinder *binder
)

This will delete the object and call onDestroy once the refcount reaches zero.

Available since API level 29.

Details
Parameters
binder
the binder object to remove a refcount from.

AIBinder_dump

binder_status_t AIBinder_dump(
  AIBinder *binder,
  int fd,
  const char **args,
  uint32_t numArgs
)

Built-in transaction for all binder objects.

This dumps information about a given binder.

See also AIBinder_Class_setOnDump, AIBinder_onDump.

Available since API level 29.

Details
Parameters
binder
the binder to dump information about
fd
where information should be dumped to
args
null-terminated arguments to pass (may be null if numArgs is 0)
numArgs
number of args to send
Returns
STATUS_OK if dump succeeds (or if there is nothing to dump)

AIBinder_fromJavaBinder

AIBinder * AIBinder_fromJavaBinder(
  JNIEnv *env,
  jobject binder
)

Converts an android.os.IBinder object into an AIBinder* object.

If the binder is null, null is returned. If this binder object was originally an AIBinder object, the original object is returned. The returned object has one refcount associated with it, and so this should be accompanied with an AIBinder_decStrong call.

Available since API level 29.

Details
Parameters
env
Java environment. Must not be null.
binder
android.os.IBinder java object.
Returns
an AIBinder object representing the Java binder object. If either parameter is null, or the Java object is of the wrong type, this will return null.

AIBinder_getCallingPid

pid_t AIBinder_getCallingPid()

This returns the calling PID assuming that this thread is called from a thread that is processing a binder transaction (for instance, in the implementation of AIBinder_Class_onTransact).

This can be used with higher-level system services to determine the caller's identity and check permissions. However, when doing this, one should be aware of possible TOCTOU problems when the calling process dies and is replaced with another process with elevated permissions and the same PID.

Warning: oneway transactions do not receive PID. Even if you expect a transaction to be synchronous, a misbehaving client could send it as a synchronous call and result in a 0 PID here. Additionally, if there is a race and the calling process dies, the PID may still be 0 for a synchronous call.

Available since API level 29.

Details
Returns
calling pid or the current process's PID if this thread isn't processing a transaction. If the transaction being processed is a oneway transaction, then this method will return 0.

AIBinder_getCallingUid

uid_t AIBinder_getCallingUid()

This returns the calling UID assuming that this thread is called from a thread that is processing a binder transaction (for instance, in the implementation of AIBinder_Class_onTransact).

This can be used with higher-level system services to determine the caller's identity and check permissions.

Available since API level 29.

Details
Returns
calling uid or the current process's UID if this thread isn't processing a transaction.

AIBinder_getClass

const AIBinder_Class * AIBinder_getClass(
  AIBinder *binder
)

Returns the class that this binder was constructed with or associated with.

Available since API level 29.

Details
Parameters
binder
the object that is being queried.
Returns
the class that this binder is associated with. If this binder wasn't created with AIBinder_new, and AIBinder_associateClass hasn't been called, then this will return null.

AIBinder_getExtension

binder_status_t AIBinder_getExtension(
  AIBinder *binder,
  AIBinder **outExt
)

Gets the extension registered with AIBinder_setExtension.

See AIBinder_setExtension.

Available since API level 30.

Details
Parameters
binder
the object to get the extension of.
outExt
the returned extension object. Will be null if there is no extension set or non-null with one strong ref count.
Returns
error of getting the interface (may be a transaction error if this is remote binder). STATUS_UNEXPECTED_NULL if binder is null.

AIBinder_getUserData

void * AIBinder_getUserData(
  AIBinder *binder
)

Value returned by onCreate for a local binder.

For stateless classes (if onCreate returns null), this also returns null. For a remote binder, this will always return null.

Available since API level 29.

Details
Parameters
binder
the object that is being queried.
Returns
the userdata returned from AIBinder_onCreate when this object was created. This may be null for stateless objects. For remote objects, this is always null.

AIBinder_incStrong

void AIBinder_incStrong(
  AIBinder *binder
)

This can only be called if a strong reference to this object already exists in process.

Available since API level 29.

Details
Parameters
binder
the binder object to add a refcount to.

AIBinder_isAlive

bool AIBinder_isAlive(
  const AIBinder *binder
)

If this binder is known to be alive.

This will not send a transaction to a remote process and returns a result based on the last known information. That is, whenever a transaction is made, this is automatically updated to reflect the current alive status of this binder. This will be updated as the result of a transaction made using AIBinder_transact, but it will also be updated based on the results of bookkeeping or other transactions made internally.

Available since API level 29.

Details
Parameters
binder
the binder being queried.
Returns
true if the binder is alive.

AIBinder_isHandlingTransaction

bool AIBinder_isHandlingTransaction()

Determine whether the current thread is currently executing an incoming transaction.

Details
Returns
true if the current thread is currently executing an incoming transaction, and false otherwise.

AIBinder_isRemote

bool AIBinder_isRemote(
  const AIBinder *binder
)

If this is hosted in a process other than the current one.

Available since API level 29.

Details
Parameters
binder
the binder being queried.
Returns
true if the AIBinder represents an object in another process.

AIBinder_linkToDeath

binder_status_t AIBinder_linkToDeath(
  AIBinder *binder,
  AIBinder_DeathRecipient *recipient,
  void *cookie
)

Registers for notifications that the associated binder is dead.

The same death recipient may be associated with multiple different binders. If the binder is local, then no death recipient will be given (since if the local process dies, then no recipient will exist to receive a transaction). The cookie is passed to recipient in the case that this binder dies and can be null. The exact cookie must also be used to unlink this transaction (see AIBinder_unlinkToDeath). This function may return a binder transaction failure. The cookie can be used both for identification and holding user data.

If binder is local, this will return STATUS_INVALID_OPERATION.

Available since API level 29.

Details
Parameters
binder
the binder object you want to receive death notifications from.
recipient
the callback that will receive notifications when/if the binder dies.
cookie
the value that will be passed to the death recipient on death.
Returns
STATUS_OK on success.

AIBinder_lt

bool AIBinder_lt(
  const AIBinder *lhs,
  const AIBinder *rhs
)

Whether AIBinder is less than another.

This provides a per-process-unique total ordering of binders where a null AIBinder* object is considered to be before all other binder objects. For instance, two binders refer to the same object in a local or remote process when both AIBinder_lt(a, b) and AIBinder_lt(b, a) are false. This API might be used to insert and lookup binders in binary search trees.

AIBinder* pointers themselves actually also create a per-process-unique total ordering. However, this ordering is inconsistent with AIBinder_Weak_lt for remote binders. So, in general, this function should be preferred.

Available since API level 31.

Details
Parameters
lhs
comparison object
rhs
comparison object
Returns
whether "lhs < rhs" is true

AIBinder_new

AIBinder * AIBinder_new(
  const AIBinder_Class *clazz,
  void *args
)

Creates a new binder object of the appropriate class.

Ownership of args is passed to this object. The lifecycle is implemented with AIBinder_incStrong and AIBinder_decStrong. When the reference count reaches zero, onDestroy is called.

When this is called, the refcount is implicitly 1. So, calling decStrong exactly one time is required to delete this object.

Once an AIBinder object is created using this API, re-creating that AIBinder for the same instance of the same class will break pointer equality for that specific AIBinder object. For instance, if someone erroneously created two AIBinder instances representing the same callback object and passed one to a hypothetical addCallback function and then later another one to a hypothetical removeCallback function, the remote process would have no way to determine that these two objects are actually equal using the AIBinder pointer alone (which they should be able to do). Also see the suggested memory ownership model suggested above.

Available since API level 29.

Details
Parameters
clazz
the type of the object to be created.
args
the args to pass to AIBinder_onCreate for that class.
Returns
a binder object representing the newly instantiated object.

AIBinder_ping

binder_status_t AIBinder_ping(
  AIBinder *binder
)

Built-in transaction for all binder objects.

This sends a transaction that will immediately return. Usually this is used to make sure that a binder is alive, as a placeholder call, or as a consistency check.

Available since API level 29.

Details
Parameters
binder
the binder being queried.
Returns
STATUS_OK if the ping succeeds.

AIBinder_prepareTransaction

binder_status_t AIBinder_prepareTransaction(
  AIBinder *binder,
  AParcel **in
)

A transaction is a series of calls to these functions which looks this.

  • call AIBinder_prepareTransaction
  • fill out the in parcel with parameters (lifetime of the 'in' variable)
  • call AIBinder_transact
  • read results from the out parcel (lifetime of the 'out' variable) Creates a parcel to start filling out for a transaction. This will add a header to the transaction that corresponds to android.os.Parcel::writeInterfaceToken. This may add debugging or other information to the transaction for platform use or to enable other features to work. The contents of this header is a platform implementation detail, and it is required to use libbinder_ndk. This parcel is to be sent via AIBinder_transact and it represents the input data to the transaction. It is recommended to check if the object is local and call directly into its user data before calling this as the parceling and unparceling cost can be avoided. This AIBinder must be either built with a class or associated with a class before using this API.

This does not affect the ownership of binder. When this function succeeds, the in parcel's ownership is passed to the caller. At this point, the parcel can be filled out and passed to AIBinder_transact. Alternatively, if there is an error while filling out the parcel, it can be deleted with AParcel_delete.

Available since API level 29.

Details
Parameters
binder
the binder object to start a transaction on.
in
out parameter for input data to the transaction.
Returns
STATUS_OK on success. This will return STATUS_INVALID_OPERATION if the binder has not yet been associated with a class (see AIBinder_new and AIBinder_associateClass).

AIBinder_setExtension

binder_status_t AIBinder_setExtension(
  AIBinder *binder,
  AIBinder *ext
)

Gets the extension of a binder interface.

This allows a downstream developer to add an extension to an interface without modifying its interface file. This should be called immediately when the object is created before it is passed to another thread. No thread safety is required.

For instance, imagine if we have this interface: interface IFoo { void doFoo(); }

A). Historical option that has proven to be BAD! Only the original author of an interface should change an interface. If someone downstream wants additional functionality, they should not ever change the interface or use this method.

BAD TO DO: interface IFoo { BAD TO DO BAD TO DO: void doFoo(); BAD TO DO BAD TO DO: + void doBar(); // adding a method BAD TO DO BAD TO DO: } BAD TO DO

B). Option that this method enables. Leave the original interface unchanged (do not change IFoo!). Instead, create a new interface in a downstream package:

package com.; // new functionality in a new package
interface IBar { void doBar(); }

When registering the interface, add: std::shared_ptr foo = new MyFoo; // class in AOSP codebase std::shared_ptr bar = new MyBar; // custom extension class SpAIBinder binder = foo->asBinder(); // target binder to extend ... = AIBinder_setExtension(binder.get(), bar->asBinder().get()); ... = AServiceManager_addService(binder.get(), instanceName); // handle error

Do not use foo->asBinder().get() as the target binder argument to AIBinder_setExtensions because asBinder it creates a new binder object that will be destroyed after the function is called. The same binder object must be used for AIBinder_setExtension and AServiceManager_addService to register the service with an extension.

Then, clients of IFoo can get this extension: SpAIBinder binder = ...; std::shared_ptr foo = IFoo::fromBinder(binder); // handle if null SpAIBinder barBinder; ... = AIBinder_getExtension(barBinder.get()); // handle error std::shared_ptr bar = IBar::fromBinder(barBinder); // type is checked with AIBinder_associateClass // if bar is null, then there is no extension or a different // type of extension

Available since API level 30.

Details
Parameters
binder
the object to get the extension on. Must be local.
ext
the extension to set (binder will hold a strong reference to this)
Returns
OK on success, STATUS_INVALID_OPERATION if binder is not local, STATUS_UNEXPECTED_NULL if either binder is null.

AIBinder_toJavaBinder

jobject AIBinder_toJavaBinder(
  JNIEnv *env,
  AIBinder *binder
)

Converts an AIBinder* object into an android.os.IBinder object.

If the binder is null, null is returned. If this binder object was originally an IBinder object, the original java object will be returned.

WARNING: this function returns global and local references. This can be figured out using GetObjectRefType. Though, when this function is called from within a Java context, the local ref will automatically be cleaned up. If this is called outside of a Java frame, PushObjectFrame/PopObjectFrame can simulate this automatic cleanup.

Available since API level 29.

Details
Parameters
env
Java environment. Must not be null.
binder
the object to convert.
Returns
an android.os.IBinder object or null if the parameters were null.

AIBinder_transact

binder_status_t AIBinder_transact(
  AIBinder *binder,
  transaction_code_t code,
  AParcel **in,
  AParcel **out,
  binder_flags_t flags
)

Transact using a parcel created from AIBinder_prepareTransaction.

This actually communicates with the object representing this binder object. This also passes out a parcel to be used for the return transaction. This takes ownership of the in parcel and automatically deletes it after it is sent to the remote process. The output parcel is the result of the transaction. If the transaction has FLAG_ONEWAY, the out parcel will be empty. Otherwise, this will block until the remote process has processed the transaction, and the out parcel will contain the output data from transaction.

This does not affect the ownership of binder. The out parcel's ownership is passed to the caller and must be released with AParcel_delete when finished reading.

Available since API level 29.

Details
Parameters
binder
the binder object to transact on.
code
the implementation-specific code representing which transaction should be taken.
in
the implementation-specific input data to this transaction.
out
the implementation-specific output data to this transaction.
flags
possible flags to alter the way in which the transaction is conducted or 0.
Returns
the result from the kernel or from the remote process. Usually, implementation-specific error codes are written to the output parcel, and the transaction code is reserved for kernel errors or error codes that have been repeated from subsequent transactions.

AIBinder_unlinkToDeath

binder_status_t AIBinder_unlinkToDeath(
  AIBinder *binder,
  AIBinder_DeathRecipient *recipient,
  void *cookie
)

Stops registration for the associated binder dying.

Does not delete the recipient. This function may return a binder transaction failure and in case the death recipient cannot be found, it returns STATUS_NAME_NOT_FOUND.

This only ever needs to be called when the AIBinder_DeathRecipient remains for use with other AIBinder objects. If the death recipient is deleted, all binders will automatically be unlinked. If the binder dies, it will automatically unlink. If the binder is deleted, it will be automatically unlinked.

Be aware that it is not safe to immediately deallocate the cookie when this call returns. If you need to clean up the cookie, you should do so in the onUnlinked callback, which can be set using AIBinder_DeathRecipient_setOnUnlinked.

Available since API level 29.

Details
Parameters
binder
the binder object to remove a previously linked death recipient from.
recipient
the callback to remove.
cookie
the cookie used to link to death.
Returns
STATUS_OK on success. STATUS_NAME_NOT_FOUND if the binder cannot be found to be unlinked.

AParcel_appendFrom

binder_status_t AParcel_appendFrom(
  const AParcel *from,
  AParcel *to,
  int32_t start,
  int32_t size
)

Copy the data of a parcel to other parcel.

Available since API level 31.

Details
Parameters
from
The source
to
The detination
start
The position where the copied data starts.
size
The amount of data which will be copied.
Returns
STATUS_OK on success.

AParcel_create

AParcel * AParcel_create()

Creates a parcel.

Available since API level 31.

Details
Returns
A parcel which is not related to any IBinder objects.

AParcel_delete

void AParcel_delete(
  AParcel *parcel
)

Cleans up a parcel.

Available since API level 29.

Details
Parameters
parcel
A parcel returned by AIBinder_prepareTransaction or AIBinder_transact when a transaction is being aborted.

AParcel_fromJavaParcel

AParcel * AParcel_fromJavaParcel(
  JNIEnv *env,
  jobject parcel
)

Converts an android.os.Parcel object into an AParcel* object.

If the parcel is null, null is returned.

Available since API level 30.

Details
Parameters
env
Java environment. Must not be null.
parcel
android.os.Parcel java object.
Returns
an AParcel object representing the Java parcel object. If either parameter is null, this will return null. This must be deleted with AParcel_delete. This does not take ownership of the jobject and is only good for as long as the jobject is alive.

AParcel_getDataPosition

int32_t AParcel_getDataPosition(
  const AParcel *parcel
)

Gets the current position within the parcel.

Available since API level 29.

Details
Parameters
parcel
The parcel of which to get the position.
Returns
The size of the parcel. This will always be greater than 0. The values returned by this function before and after calling various reads and writes are not defined. Only the delta between two positions between a specific sequence of calls is defined. For instance, if position is X, writeBool is called, and then position is Y, readBool can be called from position X will return the same value, and then position will be Y.

AParcel_getDataSize

int32_t AParcel_getDataSize(
  const AParcel *parcel
)

Gets the size of the parcel.

Available since API level 31.

Details
Parameters
parcel
The parcel of which to get the size.
Returns
The size of the parcel.

AParcel_marshal

binder_status_t AParcel_marshal(
  const AParcel *parcel,
  uint8_t *buffer,
  size_t start,
  size_t len
)

Marshals the raw bytes of the Parcel to a buffer.

Available since API level 33.

The parcel must not contain any binders or file descriptors.

The data you retrieve here must not be placed in any kind of persistent storage. (on local disk, across a network, etc). For that, you should use standard serialization or another kind of general serialization mechanism. The Parcel marshalled representation is highly optimized for local IPC, and as such does not attempt to maintain compatibility with data created in different versions of the platform.

Details
Parameters
parcel
The parcel of which to get the data.
buffer
The buffer to copy the raw bytes to.
start
The start position in the buffer to copy from.
len
The size of the data to copy, buffer size must be larger or equal to this.
Returns
STATUS_OK on success, STATUS_INVALID_OPERATION if parcel contains binders or file descriptors. STATUS_BAD_VALUE if the buffer size is less than parcel size.

AParcel_readBool

binder_status_t AParcel_readBool(
  const AParcel *parcel,
  bool *value
)

Reads into bool value from the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to read from.
value
the value to read from the parcel.
Returns
STATUS_OK on successful read.

AParcel_readBoolArray

binder_status_t AParcel_readBoolArray(
  const AParcel *parcel,
  void *arrayData,
  AParcel_boolArrayAllocator allocator,
  AParcel_boolArraySetter setter
)

Reads an array of bool from the next location in a non-null parcel.

First, allocator will be called with the length of the array. Then, for every i in [0, length), setter(arrayData, i, x) will be called where x is the value at the associated index.

Available since API level 29.

Details
Parameters
parcel
the parcel to read from.
arrayData
some external representation of an array.
allocator
the callback that will be called to allocate the array.
setter
the callback that will be called to set a value at a specific location in the array.
Returns
STATUS_OK on successful read.

AParcel_readByte

binder_status_t AParcel_readByte(
  const AParcel *parcel,
  int8_t *value
)

Reads into int8_t value from the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to read from.
value
the value to read from the parcel.
Returns
STATUS_OK on successful read.

AParcel_readByteArray

binder_status_t AParcel_readByteArray(
  const AParcel *parcel,
  void *arrayData,
  AParcel_byteArrayAllocator allocator
)

Reads an array of int8_t from the next location in a non-null parcel.

First, allocator will be called with the length of the array. If the allocation succeeds and the length is greater than zero, the buffer returned by the allocator will be filled with the corresponding data

Available since API level 29.

Details
Parameters
parcel
the parcel to read from.
arrayData
some external representation of an array.
allocator
the callback that will be called to allocate the array.
Returns
STATUS_OK on successful read.

AParcel_readChar

binder_status_t AParcel_readChar(
  const AParcel *parcel,
  char16_t *value
)

Reads into char16_t value from the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to read from.
value
the value to read from the parcel.
Returns
STATUS_OK on successful read.

AParcel_readCharArray

binder_status_t AParcel_readCharArray(
  const AParcel *parcel,
  void *arrayData,
  AParcel_charArrayAllocator allocator
)

Reads an array of char16_t from the next location in a non-null parcel.

First, allocator will be called with the length of the array. If the allocation succeeds and the length is greater than zero, the buffer returned by the allocator will be filled with the corresponding data

Available since API level 29.

Details
Parameters
parcel
the parcel to read from.
arrayData
some external representation of an array.
allocator
the callback that will be called to allocate the array.
Returns
STATUS_OK on successful read.

AParcel_readDouble

binder_status_t AParcel_readDouble(
  const AParcel *parcel,
  double *value
)

Reads into double value from the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to read from.
value
the value to read from the parcel.
Returns
STATUS_OK on successful read.

AParcel_readDoubleArray

binder_status_t AParcel_readDoubleArray(
  const AParcel *parcel,
  void *arrayData,
  AParcel_doubleArrayAllocator allocator
)

Reads an array of double from the next location in a non-null parcel.

First, allocator will be called with the length of the array. If the allocation succeeds and the length is greater than zero, the buffer returned by the allocator will be filled with the corresponding data

Available since API level 29.

Details
Parameters
parcel
the parcel to read from.
arrayData
some external representation of an array.
allocator
the callback that will be called to allocate the array.
Returns
STATUS_OK on successful read.

AParcel_readFloat

binder_status_t AParcel_readFloat(
  const AParcel *parcel,
  float *value
)

Reads into float value from the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to read from.
value
the value to read from the parcel.
Returns
STATUS_OK on successful read.

AParcel_readFloatArray

binder_status_t AParcel_readFloatArray(
  const AParcel *parcel,
  void *arrayData,
  AParcel_floatArrayAllocator allocator
)

Reads an array of float from the next location in a non-null parcel.

First, allocator will be called with the length of the array. If the allocation succeeds and the length is greater than zero, the buffer returned by the allocator will be filled with the corresponding data

Available since API level 29.

Details
Parameters
parcel
the parcel to read from.
arrayData
some external representation of an array.
allocator
the callback that will be called to allocate the array.
Returns
STATUS_OK on successful read.

AParcel_readInt32

binder_status_t AParcel_readInt32(
  const AParcel *parcel,
  int32_t *value
)

Reads into int32_t value from the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to read from.
value
the value to read from the parcel.
Returns
STATUS_OK on successful read.

AParcel_readInt32Array

binder_status_t AParcel_readInt32Array(
  const AParcel *parcel,
  void *arrayData,
  AParcel_int32ArrayAllocator allocator
)

Reads an array of int32_t from the next location in a non-null parcel.

First, allocator will be called with the length of the array. If the allocation succeeds and the length is greater than zero, the buffer returned by the allocator will be filled with the corresponding data

Available since API level 29.

Details
Parameters
parcel
the parcel to read from.
arrayData
some external representation of an array.
allocator
the callback that will be called to allocate the array.
Returns
STATUS_OK on successful read.

AParcel_readInt64

binder_status_t AParcel_readInt64(
  const AParcel *parcel,
  int64_t *value
)

Reads into int64_t value from the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to read from.
value
the value to read from the parcel.
Returns
STATUS_OK on successful read.

AParcel_readInt64Array

binder_status_t AParcel_readInt64Array(
  const AParcel *parcel,
  void *arrayData,
  AParcel_int64ArrayAllocator allocator
)

Reads an array of int64_t from the next location in a non-null parcel.

First, allocator will be called with the length of the array. If the allocation succeeds and the length is greater than zero, the buffer returned by the allocator will be filled with the corresponding data

Available since API level 29.

Details
Parameters
parcel
the parcel to read from.
arrayData
some external representation of an array.
allocator
the callback that will be called to allocate the array.
Returns
STATUS_OK on successful read.

AParcel_readParcelFileDescriptor

binder_status_t AParcel_readParcelFileDescriptor(
  const AParcel *parcel,
  int *fd
)

Reads an int from the next location in a non-null parcel.

The returned fd must be closed.

This corresponds to the SDK's android.os.ParcelFileDescriptor.

Available since API level 29.

Details
Parameters
parcel
the parcel to read from.
fd
the out parameter for what is read from the parcel (or -1 to represent a null ParcelFileDescriptor)
Returns
STATUS_OK on successful write.

AParcel_readParcelableArray

binder_status_t AParcel_readParcelableArray(
  const AParcel *parcel,
  void *arrayData,
  AParcel_parcelableArrayAllocator allocator,
  AParcel_readParcelableElement elementReader
)

Reads an array of parcelables (user-defined types) from the next location in a non-null parcel.

First, allocator will be called with the length of the array. If the allocation succeeds and the length is greater than zero, elementReader will be called for every index to read the corresponding parcelable.

Available since API level 29.

Details
Parameters
parcel
the parcel to read from.
arrayData
some external representation of an array.
allocator
the callback that will be called to allocate the array.
elementReader
the callback that will be called to fill out individual elements.
Returns
STATUS_OK on successful read.

AParcel_readStatusHeader

binder_status_t AParcel_readStatusHeader(
  const AParcel *parcel,
  AStatus **status
)

Reads an AStatus from the next location in a non-null parcel.

Ownership is passed to the caller of this function.

Available since API level 29.

Details
Parameters
parcel
the parcel to read from.
status
the out parameter for what is read from the parcel.
Returns
STATUS_OK on successful write.

AParcel_readString

binder_status_t AParcel_readString(
  const AParcel *parcel,
  void *stringData,
  AParcel_stringAllocator allocator
)

Reads and allocates utf-8 string value from the next location in a non-null parcel.

Data is passed to the string allocator once the string size is known. This size includes the space for the null-terminator of this string. This allocator returns a buffer which is used as the output buffer from this read. If there is a 'null' string on the binder buffer, the allocator will be called with length -1.

Available since API level 29.

Details
Parameters
parcel
the parcel to read from.
stringData
some external representation of a string.
allocator
allocator that will be called once the size of the string is known.
Returns
STATUS_OK on successful write.

AParcel_readStringArray

binder_status_t AParcel_readStringArray(
  const AParcel *parcel,
  void *arrayData,
  AParcel_stringArrayAllocator allocator,
  AParcel_stringArrayElementAllocator elementAllocator
)

Reads and allocates utf-8 string array value from the next location in a non-null parcel.

First, AParcel_stringArrayAllocator will be called with the size of the array to be read where length is the length of the array to be read from the parcel. Then, for each index i in [0, length), AParcel_stringArrayElementAllocator will be called with the length of the string to be read from the parcel. The resultant buffer from each of these calls will be filled according to the contents of the string that is read. If the string array being read is 'null', this will instead just pass -1 to AParcel_stringArrayAllocator.

Available since API level 29.

Details
Parameters
parcel
the parcel to read from.
arrayData
some external representation of an array.
allocator
the callback that will be called with arrayData once the size of the output array is known.
elementAllocator
the callback that will be called on every index of arrayData to allocate the string at that location.
Returns
STATUS_OK on successful read.

AParcel_readStrongBinder

binder_status_t AParcel_readStrongBinder(
  const AParcel *parcel,
  AIBinder **binder
)

Reads an AIBinder from the next location in a non-null parcel.

One strong ref-count of ownership is passed to the caller of this function.

Available since API level 29.

Details
Parameters
parcel
the parcel to read from.
binder
the out parameter for what is read from the parcel. This may be null.
Returns
STATUS_OK on successful write.

AParcel_readUint32

binder_status_t AParcel_readUint32(
  const AParcel *parcel,
  uint32_t *value
)

Reads into uint32_t value from the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to read from.
value
the value to read from the parcel.
Returns
STATUS_OK on successful read.

AParcel_readUint32Array

binder_status_t AParcel_readUint32Array(
  const AParcel *parcel,
  void *arrayData,
  AParcel_uint32ArrayAllocator allocator
)

Reads an array of uint32_t from the next location in a non-null parcel.

First, allocator will be called with the length of the array. If the allocation succeeds and the length is greater than zero, the buffer returned by the allocator will be filled with the corresponding data

Available since API level 29.

Details
Parameters
parcel
the parcel to read from.
arrayData
some external representation of an array.
allocator
the callback that will be called to allocate the array.
Returns
STATUS_OK on successful read.

AParcel_readUint64

binder_status_t AParcel_readUint64(
  const AParcel *parcel,
  uint64_t *value
)

Reads into uint64_t value from the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to read from.
value
the value to read from the parcel.
Returns
STATUS_OK on successful read.

AParcel_readUint64Array

binder_status_t AParcel_readUint64Array(
  const AParcel *parcel,
  void *arrayData,
  AParcel_uint64ArrayAllocator allocator
)

Reads an array of uint64_t from the next location in a non-null parcel.

First, allocator will be called with the length of the array. If the allocation succeeds and the length is greater than zero, the buffer returned by the allocator will be filled with the corresponding data

Available since API level 29.

Details
Parameters
parcel
the parcel to read from.
arrayData
some external representation of an array.
allocator
the callback that will be called to allocate the array.
Returns
STATUS_OK on successful read.

AParcel_reset

binder_status_t AParcel_reset(
  AParcel *parcel
)

Reset the parcel to the initial status.

Available since API level 31.

Details
Parameters
parcel
The parcel of which to be reset.
Returns
STATUS_OK on success.

AParcel_setDataPosition

binder_status_t AParcel_setDataPosition(
  const AParcel *parcel,
  int32_t position
)

Sets the position within the parcel.

This must be called with a position that has been previously returned from AParcel_getDataPosition. If writes are made after setting the data position, they must be made in the exact same sequence used before resetting data position. Writing over objects such as binders or file descriptors is not supported.

Available since API level 29.

Details
Parameters
parcel
The parcel of which to set the position.
position
Position of the parcel to set. This must be a value returned by AParcel_getDataPosition. Positions are constant for a given parcel between processes.
Returns
STATUS_OK on success. If position is negative, then STATUS_BAD_VALUE will be returned.

AParcel_unmarshal

binder_status_t AParcel_unmarshal(
  AParcel *parcel,
  const uint8_t *buffer,
  size_t len
)

Set the data in the parcel to the raw bytes from the buffer.

Available since API level 33.

Details
Parameters
parcel
The parcel to set data.
buffer
The data buffer to set.
len
The size of the data to set.
Returns
STATUS_OK on success.

AParcel_writeBool

binder_status_t AParcel_writeBool(
  AParcel *parcel,
  bool value
)

Writes bool value to the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to write to.
value
the value to write to the parcel.
Returns
STATUS_OK on successful write.

AParcel_writeBoolArray

binder_status_t AParcel_writeBoolArray(
  AParcel *parcel,
  const void *arrayData,
  int32_t length,
  AParcel_boolArrayGetter getter
)

Writes an array of bool to the next location in a non-null parcel.

getter(arrayData, i) will be called for each i in [0, length) in order to get the underlying values to write to the parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to write to.
arrayData
some external representation of an array.
length
the length of arrayData (or -1 if this represents a null array).
getter
the callback to retrieve data at specific locations in the array.
Returns
STATUS_OK on successful write.

AParcel_writeByte

binder_status_t AParcel_writeByte(
  AParcel *parcel,
  int8_t value
)

Writes int8_t value to the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to write to.
value
the value to write to the parcel.
Returns
STATUS_OK on successful write.

AParcel_writeByteArray

binder_status_t AParcel_writeByteArray(
  AParcel *parcel,
  const int8_t *arrayData,
  int32_t length
)

Writes an array of int8_t to the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to write to.
arrayData
an array of size 'length' (or null if length is -1, may be null if length is 0).
length
the length of arrayData or -1 if this represents a null array.
Returns
STATUS_OK on successful write.

AParcel_writeChar

binder_status_t AParcel_writeChar(
  AParcel *parcel,
  char16_t value
)

Writes char16_t value to the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to write to.
value
the value to write to the parcel.
Returns
STATUS_OK on successful write.

AParcel_writeCharArray

binder_status_t AParcel_writeCharArray(
  AParcel *parcel,
  const char16_t *arrayData,
  int32_t length
)

Writes an array of char16_t to the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to write to.
arrayData
an array of size 'length' (or null if length is -1, may be null if length is 0).
length
the length of arrayData or -1 if this represents a null array.
Returns
STATUS_OK on successful write.

AParcel_writeDouble

binder_status_t AParcel_writeDouble(
  AParcel *parcel,
  double value
)

Writes double value to the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to write to.
value
the value to write to the parcel.
Returns
STATUS_OK on successful write.

AParcel_writeDoubleArray

binder_status_t AParcel_writeDoubleArray(
  AParcel *parcel,
  const double *arrayData,
  int32_t length
)

Writes an array of double to the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to write to.
arrayData
an array of size 'length' (or null if length is -1, may be null if length is 0).
length
the length of arrayData or -1 if this represents a null array.
Returns
STATUS_OK on successful write.

AParcel_writeFloat

binder_status_t AParcel_writeFloat(
  AParcel *parcel,
  float value
)

Writes float value to the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to write to.
value
the value to write to the parcel.
Returns
STATUS_OK on successful write.

AParcel_writeFloatArray

binder_status_t AParcel_writeFloatArray(
  AParcel *parcel,
  const float *arrayData,
  int32_t length
)

Writes an array of float to the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to write to.
arrayData
an array of size 'length' (or null if length is -1, may be null if length is 0).
length
the length of arrayData or -1 if this represents a null array.
Returns
STATUS_OK on successful write.

AParcel_writeInt32

binder_status_t AParcel_writeInt32(
  AParcel *parcel,
  int32_t value
)

Writes int32_t value to the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to write to.
value
the value to write to the parcel.
Returns
STATUS_OK on successful write.

AParcel_writeInt32Array

binder_status_t AParcel_writeInt32Array(
  AParcel *parcel,
  const int32_t *arrayData,
  int32_t length
)

Writes an array of int32_t to the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to write to.
arrayData
an array of size 'length' (or null if length is -1, may be null if length is 0).
length
the length of arrayData or -1 if this represents a null array.
Returns
STATUS_OK on successful write.

AParcel_writeInt64

binder_status_t AParcel_writeInt64(
  AParcel *parcel,
  int64_t value
)

Writes int64_t value to the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to write to.
value
the value to write to the parcel.
Returns
STATUS_OK on successful write.

AParcel_writeInt64Array

binder_status_t AParcel_writeInt64Array(
  AParcel *parcel,
  const int64_t *arrayData,
  int32_t length
)

Writes an array of int64_t to the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to write to.
arrayData
an array of size 'length' (or null if length is -1, may be null if length is 0).
length
the length of arrayData or -1 if this represents a null array.
Returns
STATUS_OK on successful write.

AParcel_writeParcelFileDescriptor

binder_status_t AParcel_writeParcelFileDescriptor(
  AParcel *parcel,
  int fd
)

Writes a file descriptor to the next location in a non-null parcel.

This does not take ownership of fd.

This corresponds to the SDK's android.os.ParcelFileDescriptor.

Available since API level 29.

Details
Parameters
parcel
the parcel to write to.
fd
the value to write to the parcel (-1 to represent a null ParcelFileDescriptor).
Returns
STATUS_OK on successful write.

AParcel_writeParcelableArray

binder_status_t AParcel_writeParcelableArray(
  AParcel *parcel,
  const void *arrayData,
  int32_t length,
  AParcel_writeParcelableElement elementWriter
)

Writes an array of parcelables (user-defined types) to the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to write to.
arrayData
an array of size 'length' (or null if length is -1, may be null if length is 0).
length
the length of arrayData or -1 if this represents a null array.
elementWriter
function to be called for every array index to write the user-defined type at that location.
Returns
STATUS_OK on successful write.

AParcel_writeStatusHeader

binder_status_t AParcel_writeStatusHeader(
  AParcel *parcel,
  const AStatus *status
)

Writes an AStatus object to the next location in a non-null parcel.

If the status is considered to be a low-level status and has no additional information other than a binder_status_t (for instance, if it is created with AStatus_fromStatus), then that status will be returned from this method and nothing will be written to the parcel. If either this happens or if writing the status object itself fails, the return value from this function should be propagated to the client, and AParcel_readStatusHeader shouldn't be called.

Available since API level 29.

Details
Parameters
parcel
the parcel to write to.
status
the value to write to the parcel.
Returns
STATUS_OK on successful write.

AParcel_writeString

binder_status_t AParcel_writeString(
  AParcel *parcel,
  const char *string,
  int32_t length
)

Writes utf-8 string value to the next location in a non-null parcel.

If length is -1, and string is nullptr, this will write a 'null' string to the parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to write to.
string
the null-terminated string to write to the parcel, at least of size 'length'.
length
the length of the string to be written.
Returns
STATUS_OK on successful write.

AParcel_writeStringArray

binder_status_t AParcel_writeStringArray(
  AParcel *parcel,
  const void *arrayData,
  int32_t length,
  AParcel_stringArrayElementGetter getter
)

Writes utf-8 string array data to the next location in a non-null parcel.

length is the length of the array. AParcel_stringArrayElementGetter will be called for all indices in range [0, length) with the arrayData provided here. The string length and buffer returned from this function will be used to fill out the data from the parcel. If length is -1, this will write a 'null' string array to the binder buffer.

Available since API level 29.

Details
Parameters
parcel
the parcel to write to.
arrayData
some external representation of an array.
length
the length of the array to be written.
getter
the callback that will be called for every index of the array to retrieve the corresponding string buffer.
Returns
STATUS_OK on successful write.

AParcel_writeStrongBinder

binder_status_t AParcel_writeStrongBinder(
  AParcel *parcel,
  AIBinder *binder
)

Writes an AIBinder to the next location in a non-null parcel.

Can be null. This does not take any refcounts of ownership of the binder from the client.

Available since API level 29.

Details
Parameters
parcel
the parcel to write to.
binder
the value to write to the parcel.
Returns
STATUS_OK on successful write.

AParcel_writeUint32

binder_status_t AParcel_writeUint32(
  AParcel *parcel,
  uint32_t value
)

Writes uint32_t value to the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to write to.
value
the value to write to the parcel.
Returns
STATUS_OK on successful write.

AParcel_writeUint32Array

binder_status_t AParcel_writeUint32Array(
  AParcel *parcel,
  const uint32_t *arrayData,
  int32_t length
)

Writes an array of uint32_t to the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to write to.
arrayData
an array of size 'length' (or null if length is -1, may be null if length is 0).
length
the length of arrayData or -1 if this represents a null array.
Returns
STATUS_OK on successful write.

AParcel_writeUint64

binder_status_t AParcel_writeUint64(
  AParcel *parcel,
  uint64_t value
)

Writes uint64_t value to the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to write to.
value
the value to write to the parcel.
Returns
STATUS_OK on successful write.

AParcel_writeUint64Array

binder_status_t AParcel_writeUint64Array(
  AParcel *parcel,
  const uint64_t *arrayData,
  int32_t length
)

Writes an array of uint64_t to the next location in a non-null parcel.

Available since API level 29.

Details
Parameters
parcel
the parcel to write to.
arrayData
an array of size 'length' (or null if length is -1, may be null if length is 0).
length
the length of arrayData or -1 if this represents a null array.
Returns
STATUS_OK on successful write.

AStatus_delete

void AStatus_delete(
  AStatus *status
)

Deletes memory associated with the status instance.

Available since API level 29.

Details
Parameters
status
the status to delete, returned from AStatus_newOk or one of the AStatus_from* APIs.

AStatus_deleteDescription

void AStatus_deleteDescription(
  const char *description
)

Delete description.

Details
Parameters
description
value from AStatus_getDescription

AStatus_fromExceptionCode

AStatus * AStatus_fromExceptionCode(
  binder_exception_t exception
)

New status with exception code.

Available since API level 29.

Details
Parameters
exception
the code that this status should represent. If this is EX_NONE, then this constructs an non-error status object.
Returns
a newly constructed status object that the caller owns.

AStatus_fromExceptionCodeWithMessage

AStatus * AStatus_fromExceptionCodeWithMessage(
  binder_exception_t exception,
  const char *message
)

New status with exception code and message.

Available since API level 29.

Details
Parameters
exception
the code that this status should represent. If this is EX_NONE, then this constructs an non-error status object.
message
the error message to associate with this status object.
Returns
a newly constructed status object that the caller owns.

AStatus_fromServiceSpecificError

AStatus * AStatus_fromServiceSpecificError(
  int32_t serviceSpecific
)

New status with a service speciic error.

This is considered to be EX_TRANSACTION_FAILED with extra information.

Available since API level 29.

Details
Parameters
serviceSpecific
an implementation defined error code.
Returns
a newly constructed status object that the caller owns.

AStatus_fromServiceSpecificErrorWithMessage

AStatus * AStatus_fromServiceSpecificErrorWithMessage(
  int32_t serviceSpecific,
  const char *message
)

New status with a service specific error and message.

This is considered to be EX_TRANSACTION_FAILED with extra information.

Available since API level 29.

Details
Parameters
serviceSpecific
an implementation defined error code.
message
the error message to associate with this status object.
Returns
a newly constructed status object that the caller owns.

AStatus_fromStatus

AStatus * AStatus_fromStatus(
  binder_status_t status
)

New status with binder_status_t.

This is typically for low level failures when a binder_status_t is returned by an API on AIBinder or AParcel, and that is to be returned from a method returning an AStatus instance. This is the least preferable way to return errors. Prefer exceptions (particularly service-specific errors) when possible.

Available since API level 29.

Details
Parameters
status
a low-level error to associate with this status object.
Returns
a newly constructed status object that the caller owns.

AStatus_getDescription

const char * AStatus_getDescription(
  const AStatus *status
)

Get human-readable description for debugging.

Available since API level 30.

Details
Parameters
status
the status being queried.
Returns
a description, must be deleted with AStatus_deleteDescription.

AStatus_getExceptionCode

binder_exception_t AStatus_getExceptionCode(
  const AStatus *status
)

The exception that this status object represents.

Available since API level 29.

Details
Parameters
status
the status being queried.
Returns
the exception code that this object represents.

AStatus_getMessage

const char * AStatus_getMessage(
  const AStatus *status
)

If there is a message associated with this status, this will return that message.

If there is no message, this will return an empty string.

The returned string has the lifetime of the status object passed into this function.

Available since API level 29.

Details
Parameters
status
the status being queried.
Returns
the message associated with this error.

AStatus_getServiceSpecificError

int32_t AStatus_getServiceSpecificError(
  const AStatus *status
)

The service specific error if this object represents one.

This function will only ever return a non-zero result if AStatus_getExceptionCode returns EX_SERVICE_SPECIFIC. If this function returns 0, the status object may still represent a different exception or status. To find out if this transaction as a whole is okay, use AStatus_isOk instead.

Available since API level 29.

Details
Parameters
status
the status being queried.
Returns
the service-specific error code if the exception code is EX_SERVICE_SPECIFIC or 0.

AStatus_getStatus

binder_status_t AStatus_getStatus(
  const AStatus *status
)

The status if this object represents one.

This function will only ever return a non-zero result if AStatus_getExceptionCode returns EX_TRANSACTION_FAILED. If this function return 0, the status object may represent a different exception or a service specific error. To find out if this transaction as a whole is okay, use AStatus_isOk instead.

Available since API level 29.

Details
Parameters
status
the status being queried.
Returns
the status code if the exception code is EX_TRANSACTION_FAILED or 0.

AStatus_isOk

bool AStatus_isOk(
  const AStatus *status
)

Whether this object represents a successful transaction.

If this function returns true, then AStatus_getExceptionCode will return EX_NONE.

Available since API level 29.

Details
Parameters
status
the status being queried.
Returns
whether the status represents a successful transaction. For more details, see below.

AStatus_newOk

AStatus * AStatus_newOk()

New status which is considered a success.

Available since API level 29.

Details
Returns
a newly constructed status object that the caller owns.