NdkBinder

#include <binder_auto_utils.h>
#include <binder_ibinder.h>
#include <binder_ibinder_jni.h>
#include <binder_interface_utils.h>
#include <binder_parcel.h>
#include <binder_parcel_utils.h>
#include <binder_status.h>

Summary

Enumerations

Anonymous Enum 15{
  FLAG_ONEWAY = 0x01
}
enum
Anonymous Enum 16{
  FIRST_CALL_TRANSACTION = 0x00000001,
  LAST_CALL_TRANSACTION = 0x00ffffff
}
enum
Anonymous Enum 17{
  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
Anonymous Enum 18{
  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

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) __INTRODUCED_IN(29) typedef
void(*
This function is executed on death receipt.
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 EXCEPTION_* types.
binder_flags_t typedef
uint32_t
binder_status_t typedef
int32_t
One of the STATUS_* values.
transaction_code_t typedef
uint32_t

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_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_Weak_delete(AIBinder_Weak *weakBinder)
void
Deletes the weak reference.
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_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_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_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_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_delete(AParcel *parcel)
void
Cleans up a parcel.
AParcel_getDataPosition(const AParcel *parcel)
int32_t
Gets the current position within the parcel.
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_setDataPosition(const AParcel *parcel, int32_t position)
Sets the position within the parcel.
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_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_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.

Classes

ndk::BnCInterface

implementation of IInterface for server (n = native)

ndk::BpCInterface

implementation of IInterface for client (p = proxy)

ndk::ICInterface

wrapper analog to IInterface

ndk::ScopedAIBinder_DeathRecipient

Convenience wrapper.

ndk::ScopedAIBinder_Weak

Convenience wrapper.

ndk::ScopedAParcel

Convenience wrapper.

ndk::ScopedAStatus

Convenience wrapper.

ndk::ScopedFileDescriptor

Convenience wrapper for a file descriptor.

ndk::SharedRefBase

analog using std::shared_ptr for internally held refcount

ndk::SpAIBinder

Represents one strong pointer to an AIBinder object.

ndk::impl::ScopedAResource

This baseclass owns a single object, used to make various classes RAII.

Namespaces

ndk
ndk::impl

Enumerations

Anonymous Enum 15

 Anonymous Enum 15
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 16

 Anonymous Enum 16
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 18

 Anonymous Enum 18

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.

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) __INTRODUCED_IN(29)

This function is executed on death receipt.

See AIBinder_linkToDeath/AIBinder_unlinkToDeath.

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 EXCEPTION_* types.

All unrecognized values are coerced into EXCEPTION_TRANSACTION_FAILED.

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

binder_flags_t

uint32_t binder_flags_t

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

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.

Details
Parameters
interfaceDescriptor
this is a unique identifier for the class. This is used internally for sanity checks on transactions.
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_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.

Details
Parameters
dump
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.

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.

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_Weak_delete

void AIBinder_Weak_delete(
  AIBinder_Weak *weakBinder
)

Deletes the weak reference.

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

Details
Parameters
weakBinder
object created with AIBinder_Weak_new.

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.

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.

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.

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!

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.

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

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 either env or 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.

Details
Parameters
env
Java environment.
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.

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.

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.

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_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.

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.

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.

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

AIBinder_isRemote

bool AIBinder_isRemote(
  const AIBinder *binder
)

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

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 recieve 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_linkToDeath). 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.

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_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.

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 sanity check.

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 may add data to the parcel for security, debugging, or other purposes. 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.

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_toJavaBinder

jobject AIBinder_toJavaBinder(
  JNIEnv *env,
  AIBinder *binder
)

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

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

Details
Parameters
env
Java environment.
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.

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.

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_delete

void AParcel_delete(
  AParcel *parcel
)

Cleans up a parcel.

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

AParcel_getDataPosition

int32_t AParcel_getDataPosition(
  const AParcel *parcel
)

Gets the current position within the parcel.

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_readBool

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

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

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.

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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.

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.

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.

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.

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.

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.

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

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.

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

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_setDataPosition

binder_status_t AParcel_setDataPosition(
  const AParcel *parcel,
  int32_t position
)

Sets the position within the parcel.

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_writeBool

binder_status_t AParcel_writeBool(
  AParcel *parcel,
  bool value
)

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

AStatus_fromExceptionCode

AStatus * AStatus_fromExceptionCode(
  binder_exception_t exception
)

New status with exception code.

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.

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.

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.

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.

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

AStatus_getExceptionCode

binder_exception_t AStatus_getExceptionCode(
  const AStatus *status
)

The exception that this status object represents.

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.

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.

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.

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.

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.

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