From 503a8d6898c1aab5d8c99937b242d0172a82e20c Mon Sep 17 00:00:00 2001 From: Steven Moreland Date: Mon, 22 Mar 2021 22:26:32 +0000 Subject: libbinder_ndk: document preferred error types The anonymous enums corresponding to binder_status_t and binder_exception_t are undocumented, but currently these show up on the developer site w/ documentation like "Anonymous Enum 19". This is aimed at fixing that and also explaining which to use when. Bug: N/A Test: N/A Change-Id: I20414858beda591fe9f4f224b7de237bed4c97ac --- libs/binder/ndk/include_ndk/android/binder_status.h | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/libs/binder/ndk/include_ndk/android/binder_status.h b/libs/binder/ndk/include_ndk/android/binder_status.h index 05b25e7c40..7b87424e7d 100644 --- a/libs/binder/ndk/include_ndk/android/binder_status.h +++ b/libs/binder/ndk/include_ndk/android/binder_status.h @@ -32,6 +32,11 @@ __BEGIN_DECLS +/** + * Low-level status types for use in binder. This is the least preferable way to + * return an error for binder services (where binder_exception_t should be used, + * particularly EX_SERVICE_SPECIFIC). + */ enum { STATUS_OK = 0, @@ -62,6 +67,10 @@ enum { */ typedef int32_t binder_status_t; +/** + * Top level exceptions types for Android binder errors, mapping to Java + * exceptions. Also see Parcel.java. + */ enum { EX_NONE = 0, EX_SECURITY = -1, @@ -170,7 +179,8 @@ __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. + * an AStatus instance. This is the least preferable way to return errors. + * Prefer exceptions (particularly service-specific errors) when possible. * * Available since API level 29. * -- cgit v1.2.3-59-g8ed1b From 7fdee829cef36d398deffc051d2a32f916795a65 Mon Sep 17 00:00:00 2001 From: Steven Moreland Date: Mon, 22 Mar 2021 22:37:49 +0000 Subject: libbinder_ndk: mv host tip to binder_status.h This ifdef warning w/ hint for NDK host users was in binder_ibinder.h. However, since binder_status.h is always included first, moving it there. Fixes: 183160548 Test: N/A Change-Id: Icd00c7769130026980d6d55fb9bc77b8561e59b3 --- libs/binder/ndk/include_ndk/android/binder_ibinder.h | 5 ----- libs/binder/ndk/include_ndk/android/binder_status.h | 5 +++++ 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/libs/binder/ndk/include_ndk/android/binder_ibinder.h b/libs/binder/ndk/include_ndk/android/binder_ibinder.h index a44c261b3b..8941e4996c 100644 --- a/libs/binder/ndk/include_ndk/android/binder_ibinder.h +++ b/libs/binder/ndk/include_ndk/android/binder_ibinder.h @@ -36,11 +36,6 @@ __BEGIN_DECLS -#ifndef __ANDROID_API__ -#error Android builds must be compiled against a specific API. If this is an \ - android platform host build, you must use libbinder_ndk_host_user. -#endif - typedef uint32_t binder_flags_t; enum { /** diff --git a/libs/binder/ndk/include_ndk/android/binder_status.h b/libs/binder/ndk/include_ndk/android/binder_status.h index 7b87424e7d..b4dc08a49b 100644 --- a/libs/binder/ndk/include_ndk/android/binder_status.h +++ b/libs/binder/ndk/include_ndk/android/binder_status.h @@ -32,6 +32,11 @@ __BEGIN_DECLS +#ifndef __ANDROID_API__ +#error Android builds must be compiled against a specific API. If this is an \ + android platform host build, you must use libbinder_ndk_host_user. +#endif + /** * Low-level status types for use in binder. This is the least preferable way to * return an error for binder services (where binder_exception_t should be used, -- cgit v1.2.3-59-g8ed1b