From 6a026a21fd23cc98836bdb411a81ee501e8f25f8 Mon Sep 17 00:00:00 2001 From: Steven Moreland Date: Tue, 18 May 2021 19:59:31 +0000 Subject: libbinder_ndk: document headers libbinder_ndk transactions always include the interface header. This design decision was originally made in order to be able to rely on this header for platform features like work source as well as rely on bits stored there which keep track of API stability and the version of libbinder being used. In the related bug, we are discussing the possibility of removing this requirement, but for now documenting it explicitly. Bug: 188022639 Test: N/A Change-Id: I5a83d6eaae9fd7832b322e490ec91f5e4f1005e2 --- libs/binder/ndk/include_ndk/android/binder_ibinder.h | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) (limited to 'libs') diff --git a/libs/binder/ndk/include_ndk/android/binder_ibinder.h b/libs/binder/ndk/include_ndk/android/binder_ibinder.h index 9e2050b411..78f2d3af14 100644 --- a/libs/binder/ndk/include_ndk/android/binder_ibinder.h +++ b/libs/binder/ndk/include_ndk/android/binder_ibinder.h @@ -150,6 +150,11 @@ typedef void (*AIBinder_Class_onDestroy)(void* userData); /** * This is called whenever a transaction needs to be processed by a local implementation. * + * This method will be called after the equivalent of + * android.os.Parcel#enforceInterface is called. That is, the interface + * descriptor associated with the AIBinder_Class descriptor will already be + * checked. + * * \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. @@ -452,12 +457,14 @@ void* AIBinder_getUserData(AIBinder* binder) __INTRODUCED_IN(29); */ /** - * 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. + * Creates a parcel to start filling out for a transaction. This will add a header to the + * transaction that corresponds to android.os.Parcel#writeInterfaceToken. This may add debugging + * or other information to the transaction for platform use or to enable other features to work. The + * contents of this header is a platform implementation detail, and it is required to use + * libbinder_ndk. This parcel is to be sent via AIBinder_transact and it represents the input data + * to the transaction. It is recommended to check if the object is local and call directly into its + * user data before calling this as the parceling and unparceling cost can be avoided. This AIBinder + * must be either built with a class or associated with a class before using this API. * * This does not affect the ownership of binder. When this function succeeds, the in parcel's * ownership is passed to the caller. At this point, the parcel can be filled out and passed to -- cgit v1.2.3-59-g8ed1b