diff options
| -rw-r--r-- | libs/binder/ndk/include_apex/android/binder_manager.h | 11 | ||||
| -rw-r--r-- | libs/binder/ndk/include_ndk/android/binder_ibinder.h | 123 | ||||
| -rw-r--r-- | libs/binder/ndk/include_ndk/android/binder_ibinder_jni.h | 11 | ||||
| -rw-r--r-- | libs/binder/ndk/include_ndk/android/binder_parcel.h | 369 | ||||
| -rw-r--r-- | libs/binder/ndk/include_ndk/android/binder_parcel_utils.h | 6 | ||||
| -rw-r--r-- | libs/binder/ndk/include_ndk/android/binder_status.h | 52 | ||||
| -rw-r--r-- | libs/binder/ndk/parcel.cpp | 34 | ||||
| -rwxr-xr-x | libs/binder/ndk/scripts/gen_parcel_helper.py | 52 |
8 files changed, 619 insertions, 39 deletions
diff --git a/libs/binder/ndk/include_apex/android/binder_manager.h b/libs/binder/ndk/include_apex/android/binder_manager.h index b8f38ba88b..80b6c07025 100644 --- a/libs/binder/ndk/include_apex/android/binder_manager.h +++ b/libs/binder/ndk/include_apex/android/binder_manager.h @@ -17,11 +17,18 @@ #pragma once #include <android/binder_ibinder.h> +#include <android/binder_status.h> __BEGIN_DECLS /** - * This registers the service with the default service manager under this instance name. + * This registers the service with the default service manager under this instance name. This does + * not take ownership of binder. + * + * \param binder object to register globally with the service manager. + * \param instance identifier of the service. This will be used to lookup the service. + * + * \return STATUS_OK on success. */ binder_status_t AServiceManager_addService(AIBinder* binder, const char* instance); @@ -29,6 +36,8 @@ binder_status_t AServiceManager_addService(AIBinder* binder, const char* instanc * Gets a binder object with this specific instance name. Blocks for a couple of seconds waiting on * it. This also implicitly calls AIBinder_incStrong (so the caller of this function is responsible * for calling AIBinder_decStrong). + * + * \param instance identifier of the service used to lookup the service. */ __attribute__((warn_unused_result)) AIBinder* AServiceManager_getService(const char* instance); diff --git a/libs/binder/ndk/include_ndk/android/binder_ibinder.h b/libs/binder/ndk/include_ndk/android/binder_ibinder.h index 04e736f744..5222bda21b 100644 --- a/libs/binder/ndk/include_ndk/android/binder_ibinder.h +++ b/libs/binder/ndk/include_ndk/android/binder_ibinder.h @@ -126,8 +126,9 @@ typedef struct AIBinder_DeathRecipient AIBinder_DeathRecipient; /** * This is called whenever a new AIBinder object is needed of a specific class. * - * These arguments are passed from AIBinder_new. The return value is stored and can be retrieved - * using AIBinder_getUserData. + * \param args these can be used to construct a new class. These are passed from AIBinder_new. + * \return this is the userdata representing the class. It can be retrieved using + * AIBinder_getUserData. */ typedef void* (*AIBinder_Class_onCreate)(void* args); @@ -135,23 +136,41 @@ typedef void* (*AIBinder_Class_onCreate)(void* args); * This is called whenever an AIBinder object is no longer referenced and needs destroyed. * * Typically, this just deletes whatever the implementation is. + * + * \param userData this is the same object returned by AIBinder_Class_onCreate */ typedef void (*AIBinder_Class_onDestroy)(void* userData); /** * This is called whenever a transaction needs to be processed by a local implementation. + * + * \param binder the object being transacted on. + * \param code implementation-specific code representing which transaction should be taken. + * \param in the implementation-specific input data to this transaction. + * \param out the implementation-specific output data to this transaction. + * + * \return 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. */ typedef binder_status_t (*AIBinder_Class_onTransact)(AIBinder* binder, transaction_code_t code, const AParcel* in, AParcel* out); /** - * An interfaceDescriptor uniquely identifies the type of object that is being created. This is used - * internally for sanity checks on transactions. + * 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 nullptr. + * None of these parameters can be null. * - * This is created one time during library initialization and cleaned up when the process exits or - * execs. + * \param interfaceDescriptor this is a unique identifier for the class. This is used internally for + * sanity checks on transactions. + * \param onCreate see AIBinder_Class_onCreate. + * \param onDestroy see AIBinder_Class_onDestroy. + * \param onTransact see AIBinder_Class_onTransact. + * + * \return the class object representing these parameters or null on error. */ __attribute__((warn_unused_result)) AIBinder_Class* AIBinder_Class_define( const char* interfaceDescriptor, AIBinder_Class_onCreate onCreate, @@ -174,12 +193,21 @@ __attribute__((warn_unused_result)) AIBinder_Class* AIBinder_Class_define( * 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. + * + * \param clazz the type of the object to be created. + * \param args the args to pass to AIBinder_onCreate for that class. + * + * \return a binder object representing the newly instantiated object. */ __attribute__((warn_unused_result)) AIBinder* AIBinder_new(const AIBinder_Class* clazz, void* args) __INTRODUCED_IN(29); /** * If this is hosted in a process other than the current one. + * + * \param binder the binder being queried. + * + * \return true if the AIBinder represents an object in another process. */ bool AIBinder_isRemote(const AIBinder* binder) __INTRODUCED_IN(29); @@ -189,13 +217,21 @@ bool AIBinder_isRemote(const AIBinder* binder) __INTRODUCED_IN(29); * 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. + * + * \param binder the binder being queried. + * + * \return true if the binder is alive. */ bool AIBinder_isAlive(const AIBinder* binder) __INTRODUCED_IN(29); /** - * Built-in transaction for all binder objects. This sends a transaction which will immediately + * 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. + * + * \param binder the binder being queried. + * + * \return STATUS_OK if the ping succeeds. */ binder_status_t AIBinder_ping(AIBinder* binder) __INTRODUCED_IN(29); @@ -209,6 +245,12 @@ binder_status_t AIBinder_ping(AIBinder* binder) __INTRODUCED_IN(29); * identification and holding user data. * * If binder is local, this will return STATUS_INVALID_OPERATION. + * + * \param binder the binder object you want to receive death notifications from. + * \param recipient the callback that will receive notifications when/if the binder dies. + * \param cookie the value that will be passed to the death recipient on death. + * + * \return STATUS_OK on success. */ binder_status_t AIBinder_linkToDeath(AIBinder* binder, AIBinder_DeathRecipient* recipient, void* cookie) __INTRODUCED_IN(29); @@ -217,22 +259,34 @@ binder_status_t AIBinder_linkToDeath(AIBinder* binder, AIBinder_DeathRecipient* * 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. + * + * \param binder the binder object to remove a previously linked death recipient from. + * \param recipient the callback to remove. + * \param cookie the cookie used to link to death. + * + * \return STATUS_OK on success. STATUS_NAME_NOT_FOUND if the binder cannot be found to be unlinked. */ binder_status_t AIBinder_unlinkToDeath(AIBinder* binder, AIBinder_DeathRecipient* recipient, void* cookie) __INTRODUCED_IN(29); /** * This can only be called if a strong reference to this object already exists in process. + * + * \param binder the binder object to add a refcount to. */ void AIBinder_incStrong(AIBinder* binder) __INTRODUCED_IN(29); /** * This will delete the object and call onDestroy once the refcount reaches zero. + * + * \param binder the binder object to remove a refcount from. */ void AIBinder_decStrong(AIBinder* binder) __INTRODUCED_IN(29); /** * For debugging only! + * + * \param binder the binder object to retrieve the refcount of. */ int32_t AIBinder_debugGetRefCount(AIBinder* binder) __INTRODUCED_IN(29); @@ -244,17 +298,32 @@ int32_t AIBinder_debugGetRefCount(AIBinder* binder) __INTRODUCED_IN(29); * * This returns true if the class association succeeds. If it fails, no change is made to the * binder object. + * + * \param binder the object to attach the class to. + * \param clazz the clazz to attach to binder. + * + * \return true if the binder has the class clazz and if the association was successful. */ bool AIBinder_associateClass(AIBinder* binder, const AIBinder_Class* clazz) __INTRODUCED_IN(29); /** * Returns the class that this binder was constructed with or associated with. + * + * \param binder the object that is being queried. + * + * \return 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. */ const AIBinder_Class* AIBinder_getClass(AIBinder* binder) __INTRODUCED_IN(29); /** * Value returned by onCreate for a local binder. For stateless classes (if onCreate returns - * nullptr), this also returns nullptr. For a remote binder, this will always return nullptr. + * null), this also returns null. For a remote binder, this will always return null. + * + * \param binder the object that is being queried. + * + * \return 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. */ void* AIBinder_getUserData(AIBinder* binder) __INTRODUCED_IN(29); @@ -278,6 +347,12 @@ void* AIBinder_getUserData(AIBinder* binder) __INTRODUCED_IN(29); * 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. + * + * \param binder the binder object to start a transaction on. + * \param in out parameter for input data to the transaction. + * + * \return 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). */ binder_status_t AIBinder_prepareTransaction(AIBinder* binder, AParcel** in) __INTRODUCED_IN(29); @@ -292,6 +367,16 @@ binder_status_t AIBinder_prepareTransaction(AIBinder* binder, AParcel** in) __IN * * 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. + * + * \param binder the binder object to transact on. + * \param code the implementation-specific code representing which transaction should be taken. + * \param in the implementation-specific input data to this transaction. + * \param out the implementation-specific output data to this transaction. + * \param flags possible flags to alter the way in which the transaction is conducted or 0. + * + * \return 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. */ binder_status_t AIBinder_transact(AIBinder* binder, transaction_code_t code, AParcel** in, AParcel** out, binder_flags_t flags) __INTRODUCED_IN(29); @@ -299,29 +384,45 @@ binder_status_t AIBinder_transact(AIBinder* binder, transaction_code_t code, APa /** * 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. + * + * \param binder object to create a weak pointer to. + * + * \return object representing a weak pointer to binder (or null if binder is null). */ __attribute__((warn_unused_result)) AIBinder_Weak* AIBinder_Weak_new(AIBinder* binder) __INTRODUCED_IN(29); /** * Deletes the weak reference. This will have no impact on the lifetime of the binder. + * + * \param weakBinder object created with AIBinder_Weak_new. */ void AIBinder_Weak_delete(AIBinder_Weak* weakBinder) __INTRODUCED_IN(29); /** * If promotion succeeds, result will have one strong refcount added to it. Otherwise, this returns - * nullptr. + * null. + * + * \param weakBinder weak pointer to attempt retrieving the original object from. + * + * \return an AIBinder object with one refcount given to the caller or null. */ __attribute__((warn_unused_result)) AIBinder* AIBinder_Weak_promote(AIBinder_Weak* weakBinder) __INTRODUCED_IN(29); /** * This function is executed on death receipt. See AIBinder_linkToDeath/AIBinder_unlinkToDeath. + * + * \param cookie the cookie passed to AIBinder_linkToDeath. */ typedef void (*AIBinder_DeathRecipient_onBinderDied)(void* cookie) __INTRODUCED_IN(29); /** * Creates a new binder death recipient. This can be attached to multiple different binder objects. + * + * \param onBinderDied the callback to call when this death recipient is invoked. + * + * \return the newly constructed object (or null if onBinderDied is null). */ __attribute__((warn_unused_result)) AIBinder_DeathRecipient* AIBinder_DeathRecipient_new( AIBinder_DeathRecipient_onBinderDied onBinderDied) __INTRODUCED_IN(29); @@ -329,6 +430,8 @@ __attribute__((warn_unused_result)) AIBinder_DeathRecipient* AIBinder_DeathRecip /** * Deletes a binder death recipient. It is not necessary to call AIBinder_unlinkToDeath before * calling this as these will all be automatically unlinked. + * + * \param recipient the binder to delete (previously created with AIBinder_DeathRecipient_new). */ void AIBinder_DeathRecipient_delete(AIBinder_DeathRecipient* recipient) __INTRODUCED_IN(29); diff --git a/libs/binder/ndk/include_ndk/android/binder_ibinder_jni.h b/libs/binder/ndk/include_ndk/android/binder_ibinder_jni.h index adb9b6e4de..124f36c55b 100644 --- a/libs/binder/ndk/include_ndk/android/binder_ibinder_jni.h +++ b/libs/binder/ndk/include_ndk/android/binder_ibinder_jni.h @@ -39,6 +39,12 @@ __BEGIN_DECLS * 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. + * + * \param env Java environment. + * \param binder android.os.IBinder java object. + * + * \return 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. */ __attribute__((warn_unused_result)) AIBinder* AIBinder_fromJavaBinder(JNIEnv* env, jobject binder) __INTRODUCED_IN(29); @@ -48,6 +54,11 @@ __attribute__((warn_unused_result)) AIBinder* AIBinder_fromJavaBinder(JNIEnv* en * * 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. + * + * \param env Java environment. + * \param binder the object to convert. + * + * \return an android.os.IBinder object or null if the parameters were null. */ __attribute__((warn_unused_result)) jobject AIBinder_toJavaBinder(JNIEnv* env, AIBinder* binder) __INTRODUCED_IN(29); diff --git a/libs/binder/ndk/include_ndk/android/binder_parcel.h b/libs/binder/ndk/include_ndk/android/binder_parcel.h index 468850da5c..a5842f70e0 100644 --- a/libs/binder/ndk/include_ndk/android/binder_parcel.h +++ b/libs/binder/ndk/include_ndk/android/binder_parcel.h @@ -47,6 +47,9 @@ typedef struct AParcel AParcel; /** * Cleans up a parcel. + * + * \param parcel A parcel returned by AIBinder_prepareTransaction or AIBinder_transact when a + * transaction is being aborted. */ void AParcel_delete(AParcel* parcel) __INTRODUCED_IN(29); @@ -59,6 +62,11 @@ void AParcel_delete(AParcel* parcel) __INTRODUCED_IN(29); * See also AParcel_readString. * * If allocation fails, null should be returned. + * + * \param stringData some external representation of a string + * \param length the length of the buffer needed to fill (including the null-terminator) + * + * \return a buffer of size 'length' or null if allocation failed. */ typedef char* (*AParcel_stringAllocator)(void* stringData, size_t length); @@ -66,6 +74,11 @@ typedef char* (*AParcel_stringAllocator)(void* stringData, size_t length); * This is called to allocate an array of size 'length'. * * See also AParcel_readStringArray + * + * \param arrayData some external representation of an array + * \param length the length to allocate this array to + * + * \return true if allocation succeeded */ typedef bool (*AParcel_stringArrayAllocator)(void* arrayData, size_t length); @@ -79,6 +92,13 @@ typedef bool (*AParcel_stringArrayAllocator)(void* arrayData, size_t length); * greater than 0. * * See also AParcel_readStringArray + * + * \param arrayData some external representation of an array. + * \param index the index at which a string should be allocated. + * \param 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. + * + * \return a buffer of size 'length' or null if allocation failed. */ typedef char* (*AParcel_stringArrayElementAllocator)(void* arrayData, size_t index, size_t length); @@ -86,6 +106,14 @@ typedef char* (*AParcel_stringArrayElementAllocator)(void* arrayData, size_t ind * This returns the length and buffer of an array at a specific index in an arrayData object. * * See also AParcel_writeStringArray + * + * \param arrayData some external representation of an array. + * \param index the index at which a string should be allocated. + * \param outLength an out parameter for the length of the string (not including the + * null-terminator) + * + * \param a null-terminated buffer of size 'outLength + 1' representing the string at the provided + * index including the null-terminator. */ typedef const char* (*AParcel_stringArrayElementGetter)(const void* arrayData, size_t index, size_t* outLength); @@ -99,6 +127,11 @@ typedef const char* (*AParcel_stringArrayElementGetter)(const void* arrayData, s * returned. * * See also AParcel_readInt32Array + * + * \param arrayData some external representation of an array of int32_t. + * \param length the length to allocate arrayData to. + * + * \return a buffer of int32_t of size 'length'. */ typedef int32_t* (*AParcel_int32ArrayAllocator)(void* arrayData, size_t length); @@ -110,6 +143,11 @@ typedef int32_t* (*AParcel_int32ArrayAllocator)(void* arrayData, size_t length); * returned. * * See also AParcel_readUint32Array + * + * \param arrayData some external representation of an array of uint32_t. + * \param length the length to allocate arrayData to. + * + * \return a buffer of uint32_t of size 'length'. */ typedef uint32_t* (*AParcel_uint32ArrayAllocator)(void* arrayData, size_t length); @@ -121,6 +159,11 @@ typedef uint32_t* (*AParcel_uint32ArrayAllocator)(void* arrayData, size_t length * returned. * * See also AParcel_readInt64Array + * + * \param arrayData some external representation of an array of int64_t. + * \param length the length to allocate arrayData to. + * + * \return a buffer of int64_t of size 'length'. */ typedef int64_t* (*AParcel_int64ArrayAllocator)(void* arrayData, size_t length); @@ -132,6 +175,11 @@ typedef int64_t* (*AParcel_int64ArrayAllocator)(void* arrayData, size_t length); * returned. * * See also AParcel_readUint64Array + * + * \param arrayData some external representation of an array of uint64_t. + * \param length the length to allocate arrayData to. + * + * \return a buffer of uint64_t of size 'length'. */ typedef uint64_t* (*AParcel_uint64ArrayAllocator)(void* arrayData, size_t length); @@ -143,6 +191,11 @@ typedef uint64_t* (*AParcel_uint64ArrayAllocator)(void* arrayData, size_t length * returned. * * See also AParcel_readFloatArray + * + * \param arrayData some external representation of an array of float. + * \param length the length to allocate arrayData to. + * + * \return a buffer of float of size 'length'. */ typedef float* (*AParcel_floatArrayAllocator)(void* arrayData, size_t length); @@ -154,6 +207,11 @@ typedef float* (*AParcel_floatArrayAllocator)(void* arrayData, size_t length); * returned. * * See also AParcel_readDoubleArray + * + * \param arrayData some external representation of an array of double. + * \param length the length to allocate arrayData to. + * + * \return a buffer of double of size 'length'. */ typedef double* (*AParcel_doubleArrayAllocator)(void* arrayData, size_t length); @@ -162,6 +220,11 @@ typedef double* (*AParcel_doubleArrayAllocator)(void* arrayData, size_t length); * a success. * * See also AParcel_readBoolArray + * + * \param arrayData some external representation of an array of bool. + * \param length the length to allocate arrayData to. + * + * \return whether the allocation succeeded. */ typedef bool (*AParcel_boolArrayAllocator)(void* arrayData, size_t length); @@ -169,6 +232,11 @@ typedef bool (*AParcel_boolArrayAllocator)(void* arrayData, size_t length); * This is called to get the underlying data from an arrayData object at index. * * See also AParcel_writeBoolArray + * + * \param arrayData some external representation of an array of bool. + * \param index the index of the value to be retrieved. + * + * \return the value of the array at index index. */ typedef bool (*AParcel_boolArrayGetter)(const void* arrayData, size_t index); @@ -176,6 +244,10 @@ typedef bool (*AParcel_boolArrayGetter)(const void* arrayData, size_t index); * This is called to set an underlying value in an arrayData object at index. * * See also AParcel_readBoolArray + * + * \param arrayData some external representation of an array of bool. + * \param index the index of the value to be set. + * \param value the value to set at index index. */ typedef void (*AParcel_boolArraySetter)(void* arrayData, size_t index, bool value); @@ -187,6 +259,11 @@ typedef void (*AParcel_boolArraySetter)(void* arrayData, size_t index, bool valu * returned. * * See also AParcel_readCharArray + * + * \param arrayData some external representation of an array of char16_t. + * \param length the length to allocate arrayData to. + * + * \return a buffer of char16_t of size 'length'. */ typedef char16_t* (*AParcel_charArrayAllocator)(void* arrayData, size_t length); @@ -198,19 +275,36 @@ typedef char16_t* (*AParcel_charArrayAllocator)(void* arrayData, size_t length); * returned. * * See also AParcel_readByteArray + * + * \param arrayData some external representation of an array of int8_t. + * \param length the length to allocate arrayData to. + * + * \return a buffer of int8_t of size 'length'. */ typedef int8_t* (*AParcel_byteArrayAllocator)(void* arrayData, size_t length); // @END-PRIMITIVE-VECTOR-GETTERS /** - * Writes an AIBinder to the next location in a non-null parcel. Can be null. + * 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. + * + * \param parcel the parcel to write to. + * \param binder the value to write to the parcel. + * + * \return STATUS_OK on successful write. */ binder_status_t AParcel_writeStrongBinder(AParcel* parcel, AIBinder* binder) __INTRODUCED_IN(29); /** * Reads an AIBinder from the next location in a non-null parcel. This will fail if the binder is * non-null. One strong ref-count of ownership is passed to the caller of this function. + * + * \param parcel the parcel to read from. + * \param binder the out parameter for what is read from the parcel. This will not be null on + * success. + * + * \return STATUS_OK on successful write. */ binder_status_t AParcel_readStrongBinder(const AParcel* parcel, AIBinder** binder) __INTRODUCED_IN(29); @@ -218,6 +312,12 @@ binder_status_t AParcel_readStrongBinder(const AParcel* parcel, AIBinder** binde /** * Reads an AIBinder from the next location in a non-null parcel. This may read a null. One strong * ref-count of ownership is passed to the caller of this function. + * + * \param parcel the parcel to read from. + * \param binder the out parameter for what is read from the parcel. This may be null even on + * success. + * + * \return STATUS_OK on successful write. */ binder_status_t AParcel_readNullableStrongBinder(const AParcel* parcel, AIBinder** binder) __INTRODUCED_IN(29); @@ -227,6 +327,11 @@ binder_status_t AParcel_readNullableStrongBinder(const AParcel* parcel, AIBinder * of fd. * * This corresponds to the SDK's android.os.ParcelFileDescriptor. + * + * \param parcel the parcel to write to. + * \param fd the value to write to the parcel. + * + * \return STATUS_OK on successful write. */ binder_status_t AParcel_writeParcelFileDescriptor(AParcel* parcel, int fd); @@ -236,6 +341,11 @@ binder_status_t AParcel_writeParcelFileDescriptor(AParcel* parcel, int fd); * The returned fd must be closed. * * This corresponds to the SDK's android.os.ParcelFileDescriptor. + * + * \param parcel the parcel to read from. + * \param binder the out parameter for what is read from the parcel. + * + * \return STATUS_OK on successful write. */ binder_status_t AParcel_readParcelFileDescriptor(const AParcel* parcel, int* fd); @@ -247,6 +357,11 @@ binder_status_t AParcel_readParcelFileDescriptor(const AParcel* parcel, int* fd) * 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. + * + * \param parcel the parcel to write to. + * \param status the value to write to the parcel. + * + * \return STATUS_OK on successful write. */ binder_status_t AParcel_writeStatusHeader(AParcel* parcel, const AStatus* status) __INTRODUCED_IN(29); @@ -254,12 +369,24 @@ binder_status_t AParcel_writeStatusHeader(AParcel* parcel, const AStatus* status /** * Reads an AStatus from the next location in a non-null parcel. Ownership is passed to the caller * of this function. + * + * \param parcel the parcel to read from. + * \param status the out parameter for what is read from the parcel. + * + * \return STATUS_OK on successful write. */ binder_status_t AParcel_readStatusHeader(const AParcel* parcel, AStatus** status) __INTRODUCED_IN(29); /** * Writes utf-8 string value to the next location in a non-null parcel. + * + * \param parcel the parcel to write to. + * \param string the null-terminated string to write to the parcel. The buffer including the null + * terminator should be of size 'length' + 1. + * \param length the length of the string to be written. + * + * \return STATUS_OK on successful write. */ binder_status_t AParcel_writeString(AParcel* parcel, const char* string, size_t length) __INTRODUCED_IN(29); @@ -270,6 +397,12 @@ binder_status_t AParcel_writeString(AParcel* parcel, const char* string, size_t * 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. + * + * \param parcel the parcel to read from. + * \param stringData some external representation of a string. + * \param allocator allocator that will be called once the size of the string is known. + * + * \return STATUS_OK on successful write. */ binder_status_t AParcel_readString(const AParcel* parcel, void* stringData, AParcel_stringAllocator allocator) __INTRODUCED_IN(29); @@ -280,6 +413,14 @@ binder_status_t AParcel_readString(const AParcel* parcel, void* stringData, * 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. + * + * \param parcel the parcel to write to. + * \param arrayData some external representation of an array. + * \param length the length of the array to be written. + * \param getter the callback that will be called for every index of the array to retrieve the + * corresponding string buffer. + * + * \return STATUS_OK on successful write. */ binder_status_t AParcel_writeStringArray(AParcel* parcel, const void* arrayData, size_t length, AParcel_stringArrayElementGetter getter) @@ -293,6 +434,15 @@ binder_status_t AParcel_writeStringArray(AParcel* parcel, const void* arrayData, * 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. + * + * \param parcel the parcel to read from. + * \param arrayData some external representation of an array. + * \param allocator the callback that will be called with arrayData once the size of the output + * array is known. + * \param elementAllocator the callback that will be called on every index of arrayData to allocate + * the string at that location. + * + * \return STATUS_OK on successful read. */ binder_status_t AParcel_readStringArray(const AParcel* parcel, void* arrayData, AParcel_stringArrayAllocator allocator, @@ -302,128 +452,254 @@ binder_status_t AParcel_readStringArray(const AParcel* parcel, void* arrayData, // @START-PRIMITIVE-READ-WRITE /** * Writes int32_t value to the next location in a non-null parcel. + * + * \param parcel the parcel to write to. + * \param value the value to write to the parcel. + * + * \return STATUS_OK on successful write. */ binder_status_t AParcel_writeInt32(AParcel* parcel, int32_t value) __INTRODUCED_IN(29); /** * Writes uint32_t value to the next location in a non-null parcel. + * + * \param parcel the parcel to write to. + * \param value the value to write to the parcel. + * + * \return STATUS_OK on successful write. */ binder_status_t AParcel_writeUint32(AParcel* parcel, uint32_t value) __INTRODUCED_IN(29); /** * Writes int64_t value to the next location in a non-null parcel. + * + * \param parcel the parcel to write to. + * \param value the value to write to the parcel. + * + * \return STATUS_OK on successful write. */ binder_status_t AParcel_writeInt64(AParcel* parcel, int64_t value) __INTRODUCED_IN(29); /** * Writes uint64_t value to the next location in a non-null parcel. + * + * \param parcel the parcel to write to. + * \param value the value to write to the parcel. + * + * \return STATUS_OK on successful write. */ binder_status_t AParcel_writeUint64(AParcel* parcel, uint64_t value) __INTRODUCED_IN(29); /** * Writes float value to the next location in a non-null parcel. + * + * \param parcel the parcel to write to. + * \param value the value to write to the parcel. + * + * \return STATUS_OK on successful write. */ binder_status_t AParcel_writeFloat(AParcel* parcel, float value) __INTRODUCED_IN(29); /** * Writes double value to the next location in a non-null parcel. + * + * \param parcel the parcel to write to. + * \param value the value to write to the parcel. + * + * \return STATUS_OK on successful write. */ binder_status_t AParcel_writeDouble(AParcel* parcel, double value) __INTRODUCED_IN(29); /** * Writes bool value to the next location in a non-null parcel. + * + * \param parcel the parcel to write to. + * \param value the value to write to the parcel. + * + * \return STATUS_OK on successful write. */ binder_status_t AParcel_writeBool(AParcel* parcel, bool value) __INTRODUCED_IN(29); /** * Writes char16_t value to the next location in a non-null parcel. + * + * \param parcel the parcel to write to. + * \param value the value to write to the parcel. + * + * \return STATUS_OK on successful write. */ binder_status_t AParcel_writeChar(AParcel* parcel, char16_t value) __INTRODUCED_IN(29); /** * Writes int8_t value to the next location in a non-null parcel. + * + * \param parcel the parcel to write to. + * \param value the value to write to the parcel. + * + * \return STATUS_OK on successful write. */ binder_status_t AParcel_writeByte(AParcel* parcel, int8_t value) __INTRODUCED_IN(29); /** * Reads into int32_t value from the next location in a non-null parcel. + * + * \param parcel the parcel to read from. + * \param value the value to read from the parcel. + * + * \return STATUS_OK on successful read. */ binder_status_t AParcel_readInt32(const AParcel* parcel, int32_t* value) __INTRODUCED_IN(29); /** * Reads into uint32_t value from the next location in a non-null parcel. + * + * \param parcel the parcel to read from. + * \param value the value to read from the parcel. + * + * \return STATUS_OK on successful read. */ binder_status_t AParcel_readUint32(const AParcel* parcel, uint32_t* value) __INTRODUCED_IN(29); /** * Reads into int64_t value from the next location in a non-null parcel. + * + * \param parcel the parcel to read from. + * \param value the value to read from the parcel. + * + * \return STATUS_OK on successful read. */ binder_status_t AParcel_readInt64(const AParcel* parcel, int64_t* value) __INTRODUCED_IN(29); /** * Reads into uint64_t value from the next location in a non-null parcel. + * + * \param parcel the parcel to read from. + * \param value the value to read from the parcel. + * + * \return STATUS_OK on successful read. */ binder_status_t AParcel_readUint64(const AParcel* parcel, uint64_t* value) __INTRODUCED_IN(29); /** * Reads into float value from the next location in a non-null parcel. + * + * \param parcel the parcel to read from. + * \param value the value to read from the parcel. + * + * \return STATUS_OK on successful read. */ binder_status_t AParcel_readFloat(const AParcel* parcel, float* value) __INTRODUCED_IN(29); /** * Reads into double value from the next location in a non-null parcel. + * + * \param parcel the parcel to read from. + * \param value the value to read from the parcel. + * + * \return STATUS_OK on successful read. */ binder_status_t AParcel_readDouble(const AParcel* parcel, double* value) __INTRODUCED_IN(29); /** * Reads into bool value from the next location in a non-null parcel. + * + * \param parcel the parcel to read from. + * \param value the value to read from the parcel. + * + * \return STATUS_OK on successful read. */ binder_status_t AParcel_readBool(const AParcel* parcel, bool* value) __INTRODUCED_IN(29); /** * Reads into char16_t value from the next location in a non-null parcel. + * + * \param parcel the parcel to read from. + * \param value the value to read from the parcel. + * + * \return STATUS_OK on successful read. */ binder_status_t AParcel_readChar(const AParcel* parcel, char16_t* value) __INTRODUCED_IN(29); /** * Reads into int8_t value from the next location in a non-null parcel. + * + * \param parcel the parcel to read from. + * \param value the value to read from the parcel. + * + * \return STATUS_OK on successful read. */ binder_status_t AParcel_readByte(const AParcel* parcel, int8_t* value) __INTRODUCED_IN(29); /** * Writes an array of int32_t to the next location in a non-null parcel. + * + * \param parcel the parcel to write to. + * \param arrayData an array of size 'length'. + * \param length the length of arrayData. + * + * \return STATUS_OK on successful write. */ -binder_status_t AParcel_writeInt32Array(AParcel* parcel, const int32_t* value, size_t length) +binder_status_t AParcel_writeInt32Array(AParcel* parcel, const int32_t* arrayData, size_t length) __INTRODUCED_IN(29); /** * Writes an array of uint32_t to the next location in a non-null parcel. + * + * \param parcel the parcel to write to. + * \param arrayData an array of size 'length'. + * \param length the length of arrayData. + * + * \return STATUS_OK on successful write. */ -binder_status_t AParcel_writeUint32Array(AParcel* parcel, const uint32_t* value, size_t length) +binder_status_t AParcel_writeUint32Array(AParcel* parcel, const uint32_t* arrayData, size_t length) __INTRODUCED_IN(29); /** * Writes an array of int64_t to the next location in a non-null parcel. + * + * \param parcel the parcel to write to. + * \param arrayData an array of size 'length'. + * \param length the length of arrayData. + * + * \return STATUS_OK on successful write. */ -binder_status_t AParcel_writeInt64Array(AParcel* parcel, const int64_t* value, size_t length) +binder_status_t AParcel_writeInt64Array(AParcel* parcel, const int64_t* arrayData, size_t length) __INTRODUCED_IN(29); /** * Writes an array of uint64_t to the next location in a non-null parcel. + * + * \param parcel the parcel to write to. + * \param arrayData an array of size 'length'. + * \param length the length of arrayData. + * + * \return STATUS_OK on successful write. */ -binder_status_t AParcel_writeUint64Array(AParcel* parcel, const uint64_t* value, size_t length) +binder_status_t AParcel_writeUint64Array(AParcel* parcel, const uint64_t* arrayData, size_t length) __INTRODUCED_IN(29); /** * Writes an array of float to the next location in a non-null parcel. + * + * \param parcel the parcel to write to. + * \param arrayData an array of size 'length'. + * \param length the length of arrayData. + * + * \return STATUS_OK on successful write. */ -binder_status_t AParcel_writeFloatArray(AParcel* parcel, const float* value, size_t length) +binder_status_t AParcel_writeFloatArray(AParcel* parcel, const float* arrayData, size_t length) __INTRODUCED_IN(29); /** * Writes an array of double to the next location in a non-null parcel. + * + * \param parcel the parcel to write to. + * \param arrayData an array of size 'length'. + * \param length the length of arrayData. + * + * \return STATUS_OK on successful write. */ -binder_status_t AParcel_writeDoubleArray(AParcel* parcel, const double* value, size_t length) +binder_status_t AParcel_writeDoubleArray(AParcel* parcel, const double* arrayData, size_t length) __INTRODUCED_IN(29); /** @@ -431,20 +707,39 @@ binder_status_t AParcel_writeDoubleArray(AParcel* parcel, const double* value, s * * getter(arrayData, i) will be called for each i in [0, length) in order to get the underlying * values to write to the parcel. + * + * \param parcel the parcel to write to. + * \param arrayData some external representation of an array. + * \param length the length of arrayData. + * \param getter the callback to retrieve data at specific locations in the array. + * + * \return STATUS_OK on successful write. */ binder_status_t AParcel_writeBoolArray(AParcel* parcel, const void* arrayData, size_t length, AParcel_boolArrayGetter getter) __INTRODUCED_IN(29); /** * Writes an array of char16_t to the next location in a non-null parcel. + * + * \param parcel the parcel to write to. + * \param arrayData an array of size 'length'. + * \param length the length of arrayData. + * + * \return STATUS_OK on successful write. */ -binder_status_t AParcel_writeCharArray(AParcel* parcel, const char16_t* value, size_t length) +binder_status_t AParcel_writeCharArray(AParcel* parcel, const char16_t* arrayData, size_t length) __INTRODUCED_IN(29); /** * Writes an array of int8_t to the next location in a non-null parcel. + * + * \param parcel the parcel to write to. + * \param arrayData an array of size 'length'. + * \param length the length of arrayData. + * + * \return STATUS_OK on successful write. */ -binder_status_t AParcel_writeByteArray(AParcel* parcel, const int8_t* value, size_t length) +binder_status_t AParcel_writeByteArray(AParcel* parcel, const int8_t* arrayData, size_t length) __INTRODUCED_IN(29); /** @@ -453,6 +748,12 @@ binder_status_t AParcel_writeByteArray(AParcel* parcel, const int8_t* value, siz * 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 + * + * \param parcel the parcel to read from. + * \param arrayData some external representation of an array. + * \param allocator the callback that will be called to allocate the array. + * + * \return STATUS_OK on successful read. */ binder_status_t AParcel_readInt32Array(const AParcel* parcel, void* arrayData, AParcel_int32ArrayAllocator allocator) __INTRODUCED_IN(29); @@ -463,6 +764,12 @@ binder_status_t AParcel_readInt32Array(const AParcel* parcel, void* arrayData, * 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 + * + * \param parcel the parcel to read from. + * \param arrayData some external representation of an array. + * \param allocator the callback that will be called to allocate the array. + * + * \return STATUS_OK on successful read. */ binder_status_t AParcel_readUint32Array(const AParcel* parcel, void* arrayData, AParcel_uint32ArrayAllocator allocator) __INTRODUCED_IN(29); @@ -473,6 +780,12 @@ binder_status_t AParcel_readUint32Array(const AParcel* parcel, void* arrayData, * 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 + * + * \param parcel the parcel to read from. + * \param arrayData some external representation of an array. + * \param allocator the callback that will be called to allocate the array. + * + * \return STATUS_OK on successful read. */ binder_status_t AParcel_readInt64Array(const AParcel* parcel, void* arrayData, AParcel_int64ArrayAllocator allocator) __INTRODUCED_IN(29); @@ -483,6 +796,12 @@ binder_status_t AParcel_readInt64Array(const AParcel* parcel, void* arrayData, * 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 + * + * \param parcel the parcel to read from. + * \param arrayData some external representation of an array. + * \param allocator the callback that will be called to allocate the array. + * + * \return STATUS_OK on successful read. */ binder_status_t AParcel_readUint64Array(const AParcel* parcel, void* arrayData, AParcel_uint64ArrayAllocator allocator) __INTRODUCED_IN(29); @@ -493,6 +812,12 @@ binder_status_t AParcel_readUint64Array(const AParcel* parcel, void* arrayData, * 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 + * + * \param parcel the parcel to read from. + * \param arrayData some external representation of an array. + * \param allocator the callback that will be called to allocate the array. + * + * \return STATUS_OK on successful read. */ binder_status_t AParcel_readFloatArray(const AParcel* parcel, void* arrayData, AParcel_floatArrayAllocator allocator) __INTRODUCED_IN(29); @@ -503,6 +828,12 @@ binder_status_t AParcel_readFloatArray(const AParcel* parcel, void* arrayData, * 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 + * + * \param parcel the parcel to read from. + * \param arrayData some external representation of an array. + * \param allocator the callback that will be called to allocate the array. + * + * \return STATUS_OK on successful read. */ binder_status_t AParcel_readDoubleArray(const AParcel* parcel, void* arrayData, AParcel_doubleArrayAllocator allocator) __INTRODUCED_IN(29); @@ -512,6 +843,14 @@ binder_status_t AParcel_readDoubleArray(const AParcel* parcel, void* arrayData, * * 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. + * + * \param parcel the parcel to read from. + * \param arrayData some external representation of an array. + * \param allocator the callback that will be called to allocate the array. + * \param setter the callback that will be called to set a value at a specific location in the + * array. + * + * \return STATUS_OK on successful read. */ binder_status_t AParcel_readBoolArray(const AParcel* parcel, void* arrayData, AParcel_boolArrayAllocator allocator, @@ -523,6 +862,12 @@ binder_status_t AParcel_readBoolArray(const AParcel* parcel, void* arrayData, * 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 + * + * \param parcel the parcel to read from. + * \param arrayData some external representation of an array. + * \param allocator the callback that will be called to allocate the array. + * + * \return STATUS_OK on successful read. */ binder_status_t AParcel_readCharArray(const AParcel* parcel, void* arrayData, AParcel_charArrayAllocator allocator) __INTRODUCED_IN(29); @@ -533,6 +878,12 @@ binder_status_t AParcel_readCharArray(const AParcel* parcel, void* arrayData, * 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 + * + * \param parcel the parcel to read from. + * \param arrayData some external representation of an array. + * \param allocator the callback that will be called to allocate the array. + * + * \return STATUS_OK on successful read. */ binder_status_t AParcel_readByteArray(const AParcel* parcel, void* arrayData, AParcel_byteArrayAllocator allocator) __INTRODUCED_IN(29); diff --git a/libs/binder/ndk/include_ndk/android/binder_parcel_utils.h b/libs/binder/ndk/include_ndk/android/binder_parcel_utils.h index 8d5e7d992e..786bcee38a 100644 --- a/libs/binder/ndk/include_ndk/android/binder_parcel_utils.h +++ b/libs/binder/ndk/include_ndk/android/binder_parcel_utils.h @@ -298,6 +298,9 @@ static inline binder_status_t AParcel_readVector(const AParcel* parcel, AParcel_stdVectorStringElementAllocator); } +/** + * Convenience API for writing the size of a vector. + */ template <typename T> static inline binder_status_t AParcel_writeVectorSize(AParcel* parcel, const std::vector<T>& vec) { if (vec.size() > INT32_MAX) { @@ -307,6 +310,9 @@ static inline binder_status_t AParcel_writeVectorSize(AParcel* parcel, const std return AParcel_writeInt32(parcel, static_cast<int32_t>(vec.size())); } +/** + * Convenience API for resizing a vector. + */ template <typename T> static inline binder_status_t AParcel_resizeVector(const AParcel* parcel, std::vector<T>* vec) { int32_t size; diff --git a/libs/binder/ndk/include_ndk/android/binder_status.h b/libs/binder/ndk/include_ndk/android/binder_status.h index a890cb90be..2671b9b6fc 100644 --- a/libs/binder/ndk/include_ndk/android/binder_status.h +++ b/libs/binder/ndk/include_ndk/android/binder_status.h @@ -95,24 +95,39 @@ typedef int32_t binder_exception_t; * along with service specific errors. * * It is not required to be used in order to parcel/receive transactions, but it is required in - * order to be compatible with standard AIDL transactions. + * order to be compatible with standard AIDL transactions since it is written as the header to the + * out parcel for transactions which get executed (don't fail during unparceling of input arguments + * or sooner). */ struct AStatus; typedef struct AStatus AStatus; /** * New status which is considered a success. + * + * \return a newly constructed status object that the caller owns. */ __attribute__((warn_unused_result)) AStatus* AStatus_newOk() __INTRODUCED_IN(29); /** * New status with exception code. + * + * \param exception the code that this status should represent. If this is EX_NONE, then this + * constructs an non-error status object. + * + * \return a newly constructed status object that the caller owns. */ __attribute__((warn_unused_result)) AStatus* AStatus_fromExceptionCode(binder_exception_t exception) __INTRODUCED_IN(29); /** * New status with exception code and message. + * + * \param exception the code that this status should represent. If this is EX_NONE, then this + * constructs an non-error status object. + * \param message the error message to associate with this status object. + * + * \return a newly constructed status object that the caller owns. */ __attribute__((warn_unused_result)) AStatus* AStatus_fromExceptionCodeWithMessage( binder_exception_t exception, const char* message) __INTRODUCED_IN(29); @@ -121,6 +136,10 @@ __attribute__((warn_unused_result)) AStatus* AStatus_fromExceptionCodeWithMessag * New status with a service speciic error. * * This is considered to be EX_TRANSACTION_FAILED with extra information. + * + * \param serviceSpecific an implementation defined error code. + * + * \return a newly constructed status object that the caller owns. */ __attribute__((warn_unused_result)) AStatus* AStatus_fromServiceSpecificError( int32_t serviceSpecific) __INTRODUCED_IN(29); @@ -129,6 +148,11 @@ __attribute__((warn_unused_result)) AStatus* AStatus_fromServiceSpecificError( * New status with a service specific error and message. * * This is considered to be EX_TRANSACTION_FAILED with extra information. + * + * \param serviceSpecific an implementation defined error code. + * \param message the error message to associate with this status object. + * + * \return a newly constructed status object that the caller owns. */ __attribute__((warn_unused_result)) AStatus* AStatus_fromServiceSpecificErrorWithMessage( int32_t serviceSpecific, const char* message) __INTRODUCED_IN(29); @@ -137,6 +161,10 @@ __attribute__((warn_unused_result)) AStatus* AStatus_fromServiceSpecificErrorWit * 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. + * + * \param a low-level error to associate with this status object. + * + * \return a newly constructed status object that the caller owns. */ __attribute__((warn_unused_result)) AStatus* AStatus_fromStatus(binder_status_t status) __INTRODUCED_IN(29); @@ -144,11 +172,19 @@ __attribute__((warn_unused_result)) AStatus* AStatus_fromStatus(binder_status_t /** * Whether this object represents a successful transaction. If this function returns true, then * AStatus_getExceptionCode will return EX_NONE. + * + * \param status the status being queried. + * + * \return whether the status represents a successful transaction. For more details, see below. */ bool AStatus_isOk(const AStatus* status) __INTRODUCED_IN(29); /** * The exception that this status object represents. + * + * \param status the status being queried. + * + * \return the exception code that this object represents. */ binder_exception_t AStatus_getExceptionCode(const AStatus* status) __INTRODUCED_IN(29); @@ -157,6 +193,10 @@ binder_exception_t AStatus_getExceptionCode(const AStatus* status) __INTRODUCED_ * 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. + * + * \param status the status being queried. + * + * \return the service-specific error code if the exception code is EX_SERVICE_SPECIFIC or 0. */ int32_t AStatus_getServiceSpecificError(const AStatus* status) __INTRODUCED_IN(29); @@ -165,6 +205,10 @@ int32_t AStatus_getServiceSpecificError(const AStatus* status) __INTRODUCED_IN(2 * 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. + * + * \param status the status being queried. + * + * \return the status code if the exception code is EX_TRANSACTION_FAILED or 0. */ binder_status_t AStatus_getStatus(const AStatus* status) __INTRODUCED_IN(29); @@ -173,11 +217,17 @@ binder_status_t AStatus_getStatus(const AStatus* status) __INTRODUCED_IN(29); * message, this will return an empty string. * * The returned string has the lifetime of the status object passed into this function. + * + * \param status the status being queried. + * + * \return the message associated with this error. */ const char* AStatus_getMessage(const AStatus* status) __INTRODUCED_IN(29); /** * Deletes memory associated with the status instance. + * + * \param status the status to delete, returned from AStatus_newOk or one of the AStatus_from* APIs. */ void AStatus_delete(AStatus* status) __INTRODUCED_IN(29); diff --git a/libs/binder/ndk/parcel.cpp b/libs/binder/ndk/parcel.cpp index cbf085e77a..8e5b4776e3 100644 --- a/libs/binder/ndk/parcel.cpp +++ b/libs/binder/ndk/parcel.cpp @@ -463,28 +463,30 @@ binder_status_t AParcel_readByte(const AParcel* parcel, int8_t* value) { return PruneStatusT(status); } -binder_status_t AParcel_writeInt32Array(AParcel* parcel, const int32_t* value, size_t length) { - return WriteArray<int32_t>(parcel, value, length); +binder_status_t AParcel_writeInt32Array(AParcel* parcel, const int32_t* arrayData, size_t length) { + return WriteArray<int32_t>(parcel, arrayData, length); } -binder_status_t AParcel_writeUint32Array(AParcel* parcel, const uint32_t* value, size_t length) { - return WriteArray<uint32_t>(parcel, value, length); +binder_status_t AParcel_writeUint32Array(AParcel* parcel, const uint32_t* arrayData, + size_t length) { + return WriteArray<uint32_t>(parcel, arrayData, length); } -binder_status_t AParcel_writeInt64Array(AParcel* parcel, const int64_t* value, size_t length) { - return WriteArray<int64_t>(parcel, value, length); +binder_status_t AParcel_writeInt64Array(AParcel* parcel, const int64_t* arrayData, size_t length) { + return WriteArray<int64_t>(parcel, arrayData, length); } -binder_status_t AParcel_writeUint64Array(AParcel* parcel, const uint64_t* value, size_t length) { - return WriteArray<uint64_t>(parcel, value, length); +binder_status_t AParcel_writeUint64Array(AParcel* parcel, const uint64_t* arrayData, + size_t length) { + return WriteArray<uint64_t>(parcel, arrayData, length); } -binder_status_t AParcel_writeFloatArray(AParcel* parcel, const float* value, size_t length) { - return WriteArray<float>(parcel, value, length); +binder_status_t AParcel_writeFloatArray(AParcel* parcel, const float* arrayData, size_t length) { + return WriteArray<float>(parcel, arrayData, length); } -binder_status_t AParcel_writeDoubleArray(AParcel* parcel, const double* value, size_t length) { - return WriteArray<double>(parcel, value, length); +binder_status_t AParcel_writeDoubleArray(AParcel* parcel, const double* arrayData, size_t length) { + return WriteArray<double>(parcel, arrayData, length); } binder_status_t AParcel_writeBoolArray(AParcel* parcel, const void* arrayData, size_t length, @@ -492,12 +494,12 @@ binder_status_t AParcel_writeBoolArray(AParcel* parcel, const void* arrayData, s return WriteArray<bool>(parcel, arrayData, length, getter, &Parcel::writeBool); } -binder_status_t AParcel_writeCharArray(AParcel* parcel, const char16_t* value, size_t length) { - return WriteArray<char16_t>(parcel, value, length); +binder_status_t AParcel_writeCharArray(AParcel* parcel, const char16_t* arrayData, size_t length) { + return WriteArray<char16_t>(parcel, arrayData, length); } -binder_status_t AParcel_writeByteArray(AParcel* parcel, const int8_t* value, size_t length) { - return WriteArray<int8_t>(parcel, value, length); +binder_status_t AParcel_writeByteArray(AParcel* parcel, const int8_t* arrayData, size_t length) { + return WriteArray<int8_t>(parcel, arrayData, length); } binder_status_t AParcel_readInt32Array(const AParcel* parcel, void* arrayData, diff --git a/libs/binder/ndk/scripts/gen_parcel_helper.py b/libs/binder/ndk/scripts/gen_parcel_helper.py index 0e10220496..bb762540e4 100755 --- a/libs/binder/ndk/scripts/gen_parcel_helper.py +++ b/libs/binder/ndk/scripts/gen_parcel_helper.py @@ -69,6 +69,11 @@ def main(): for pretty, cpp in data_types: header += "/**\n" header += " * Writes " + cpp + " value to the next location in a non-null parcel.\n" + header += " *\n" + header += " * \\param parcel the parcel to write to.\n" + header += " * \\param value the value to write to the parcel.\n" + header += " *\n" + header += " * \\return STATUS_OK on successful write.\n" header += " */\n" header += "binder_status_t AParcel_write" + pretty + "(AParcel* parcel, " + cpp + " value) __INTRODUCED_IN(29);\n\n" source += "binder_status_t AParcel_write" + pretty + "(AParcel* parcel, " + cpp + " value) {\n" @@ -79,6 +84,11 @@ def main(): for pretty, cpp in data_types: header += "/**\n" header += " * Reads into " + cpp + " value from the next location in a non-null parcel.\n" + header += " *\n" + header += " * \\param parcel the parcel to read from.\n" + header += " * \\param value the value to read from the parcel.\n" + header += " *\n" + header += " * \\return STATUS_OK on successful read.\n" header += " */\n" header += "binder_status_t AParcel_read" + pretty + "(const AParcel* parcel, " + cpp + "* value) __INTRODUCED_IN(29);\n\n" source += "binder_status_t AParcel_read" + pretty + "(const AParcel* parcel, " + cpp + "* value) {\n" @@ -89,9 +99,9 @@ def main(): for pretty, cpp in data_types: nca = pretty in non_contiguously_addressable - arg_types = "const " + cpp + "* value, size_t length" + arg_types = "const " + cpp + "* arrayData, size_t length" if nca: arg_types = "const void* arrayData, size_t length, AParcel_" + pretty.lower() + "ArrayGetter getter" - args = "value, length" + args = "arrayData, length" if nca: args = "arrayData, length, getter, &Parcel::write" + pretty header += "/**\n" @@ -100,6 +110,17 @@ def main(): header += " *\n" header += " * getter(arrayData, i) will be called for each i in [0, length) in order to get the underlying values to write " header += "to the parcel.\n" + header += " *\n" + header += " * \\param parcel the parcel to write to.\n" + if nca: + header += " * \\param arrayData some external representation of an array.\n" + header += " * \\param length the length of arrayData.\n" + header += " * \\param getter the callback to retrieve data at specific locations in the array.\n" + else: + header += " * \\param arrayData an array of size 'length'.\n" + header += " * \\param length the length of arrayData.\n" + header += " *\n" + header += " * \\return STATUS_OK on successful write.\n" header += " */\n" header += "binder_status_t AParcel_write" + pretty + "Array(AParcel* parcel, " + arg_types + ") __INTRODUCED_IN(29);\n\n" source += "binder_status_t AParcel_write" + pretty + "Array(AParcel* parcel, " + arg_types + ") {\n" @@ -121,6 +142,11 @@ def main(): pre_header += "a success.\n" pre_header += " *\n" pre_header += " * See also " + read_func + "\n" + pre_header += " *\n" + pre_header += " * \\param arrayData some external representation of an array of " + cpp + ".\n" + pre_header += " * \\param length the length to allocate arrayData to.\n" + pre_header += " *\n" + pre_header += " * \\return whether the allocation succeeded.\n" pre_header += " */\n" pre_header += "typedef bool (*" + allocator_type + ")(void* arrayData, size_t length);\n\n" @@ -128,6 +154,11 @@ def main(): pre_header += " * This is called to get the underlying data from an arrayData object at index.\n" pre_header += " *\n" pre_header += " * See also " + write_func + "\n" + pre_header += " *\n" + pre_header += " * \\param arrayData some external representation of an array of " + cpp + ".\n" + pre_header += " * \\param index the index of the value to be retrieved.\n" + pre_header += " *\n" + pre_header += " * \\return the value of the array at index index.\n" pre_header += " */\n" pre_header += "typedef " + cpp + " (*" + getter_type + ")(const void* arrayData, size_t index);\n\n" @@ -135,6 +166,10 @@ def main(): pre_header += " * This is called to set an underlying value in an arrayData object at index.\n" pre_header += " *\n" pre_header += " * See also " + read_func + "\n" + pre_header += " *\n" + pre_header += " * \\param arrayData some external representation of an array of " + cpp + ".\n" + pre_header += " * \\param index the index of the value to be set.\n" + pre_header += " * \\param value the value to set at index index.\n" pre_header += " */\n" pre_header += "typedef void (*" + setter_type + ")(void* arrayData, size_t index, " + cpp + " value);\n\n" else: @@ -146,6 +181,11 @@ def main(): pre_header += "returned.\n" pre_header += " *\n" pre_header += " * See also " + read_func + "\n" + pre_header += " *\n" + pre_header += " * \\param arrayData some external representation of an array of " + cpp + ".\n" + pre_header += " * \\param length the length to allocate arrayData to.\n" + pre_header += " *\n" + pre_header += " * \\return a buffer of " + cpp + " of size 'length'.\n" pre_header += " */\n" pre_header += "typedef " + cpp + "* (*" + allocator_type + ")(void* arrayData, size_t length);\n\n" @@ -166,6 +206,14 @@ def main(): else: header += " * First, allocator will be called with the length of the array. If the allocation succeeds and the " header += "length is greater than zero, the buffer returned by the allocator will be filled with the corresponding data\n" + header += " *\n" + header += " * \\param parcel the parcel to read from.\n" + header += " * \\param arrayData some external representation of an array.\n" + header += " * \\param allocator the callback that will be called to allocate the array.\n" + if nca: + header += " * \\param setter the callback that will be called to set a value at a specific location in the array.\n" + header += " *\n" + header += " * \\return STATUS_OK on successful read.\n" header += " */\n" header += "binder_status_t " + read_func + "(" + read_type_args + ") __INTRODUCED_IN(29);\n\n" source += "binder_status_t " + read_func + "(" + read_type_args + ") {\n" |