1 /* 2 * Copyright (C) 2018 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 /** 18 * @addtogroup NdkBinder 19 * @{ 20 */ 21 22 /** 23 * @file binder_status.h 24 */ 25 26 #pragma once 27 28 #include <errno.h> 29 #include <stdbool.h> 30 #include <stdint.h> 31 #include <sys/cdefs.h> 32 33 __BEGIN_DECLS 34 35 #ifndef __BIONIC__ 36 37 #ifndef __INTRODUCED_IN 38 #define __INTRODUCED_IN(n) 39 #endif 40 41 #ifndef __assert 42 #define __assert(a, b, c) \ 43 do { \ 44 syslog(LOG_ERR, a ": " c); \ 45 abort(); \ 46 } while (false) 47 #endif 48 49 #ifndef __ANDROID_API__ 50 #define __ANDROID_API__ 10000 51 #endif 52 53 #endif // __BIONIC__ 54 55 /** 56 * Low-level status types for use in binder. This is the least preferable way to 57 * return an error for binder services (where binder_exception_t should be used, 58 * particularly EX_SERVICE_SPECIFIC). 59 */ 60 enum { 61 STATUS_OK = 0, 62 63 STATUS_UNKNOWN_ERROR = (-2147483647 - 1), // INT32_MIN value 64 STATUS_NO_MEMORY = -ENOMEM, 65 STATUS_INVALID_OPERATION = -ENOSYS, 66 STATUS_BAD_VALUE = -EINVAL, 67 STATUS_BAD_TYPE = (STATUS_UNKNOWN_ERROR + 1), 68 STATUS_NAME_NOT_FOUND = -ENOENT, 69 STATUS_PERMISSION_DENIED = -EPERM, 70 STATUS_NO_INIT = -ENODEV, 71 STATUS_ALREADY_EXISTS = -EEXIST, 72 STATUS_DEAD_OBJECT = -EPIPE, 73 STATUS_FAILED_TRANSACTION = (STATUS_UNKNOWN_ERROR + 2), 74 STATUS_BAD_INDEX = -EOVERFLOW, 75 STATUS_NOT_ENOUGH_DATA = -ENODATA, 76 STATUS_WOULD_BLOCK = -EWOULDBLOCK, 77 STATUS_TIMED_OUT = -ETIMEDOUT, 78 STATUS_UNKNOWN_TRANSACTION = -EBADMSG, 79 STATUS_FDS_NOT_ALLOWED = (STATUS_UNKNOWN_ERROR + 7), 80 STATUS_UNEXPECTED_NULL = (STATUS_UNKNOWN_ERROR + 8), 81 }; 82 83 /** 84 * One of the STATUS_* values. 85 * 86 * All unrecognized values are coerced into STATUS_UNKNOWN_ERROR. 87 */ 88 typedef int32_t binder_status_t; 89 90 /** 91 * Top level exceptions types for Android binder errors, mapping to Java 92 * exceptions. Also see Parcel.java. 93 */ 94 enum { 95 EX_NONE = 0, 96 EX_SECURITY = -1, 97 EX_BAD_PARCELABLE = -2, 98 EX_ILLEGAL_ARGUMENT = -3, 99 EX_NULL_POINTER = -4, 100 EX_ILLEGAL_STATE = -5, 101 EX_NETWORK_MAIN_THREAD = -6, 102 EX_UNSUPPORTED_OPERATION = -7, 103 EX_SERVICE_SPECIFIC = -8, 104 EX_PARCELABLE = -9, 105 106 /** 107 * This is special, and indicates to native binder proxies that the 108 * transaction has failed at a low level. 109 */ 110 EX_TRANSACTION_FAILED = -129, 111 }; 112 113 /** 114 * One of the EXCEPTION_* types. 115 * 116 * All unrecognized values are coerced into EXCEPTION_TRANSACTION_FAILED. 117 * 118 * These exceptions values are used by the SDK for parcelables. Also see Parcel.java. 119 */ 120 typedef int32_t binder_exception_t; 121 122 /** 123 * This is a helper class that encapsulates a standard way to keep track of and chain binder errors 124 * along with service specific errors. 125 * 126 * It is not required to be used in order to parcel/receive transactions, but it is required in 127 * order to be compatible with standard AIDL transactions since it is written as the header to the 128 * out parcel for transactions which get executed (don't fail during unparceling of input arguments 129 * or sooner). 130 */ 131 struct AStatus; 132 typedef struct AStatus AStatus; 133 134 /** 135 * New status which is considered a success. 136 * 137 * Available since API level 29. 138 * 139 * \return a newly constructed status object that the caller owns. 140 */ 141 __attribute__((warn_unused_result)) AStatus* AStatus_newOk() __INTRODUCED_IN(29); 142 143 /** 144 * New status with exception code. 145 * 146 * Available since API level 29. 147 * 148 * \param exception the code that this status should represent. If this is EX_NONE, then this 149 * constructs an non-error status object. 150 * 151 * \return a newly constructed status object that the caller owns. 152 */ 153 __attribute__((warn_unused_result)) AStatus* AStatus_fromExceptionCode(binder_exception_t exception) 154 __INTRODUCED_IN(29); 155 156 /** 157 * New status with exception code and message. 158 * 159 * Available since API level 29. 160 * 161 * \param exception the code that this status should represent. If this is EX_NONE, then this 162 * constructs an non-error status object. 163 * \param message the error message to associate with this status object. 164 * 165 * \return a newly constructed status object that the caller owns. 166 */ 167 __attribute__((warn_unused_result)) AStatus* AStatus_fromExceptionCodeWithMessage( 168 binder_exception_t exception, const char* message) __INTRODUCED_IN(29); 169 170 /** 171 * New status with a service speciic error. 172 * 173 * This is considered to be EX_TRANSACTION_FAILED with extra information. 174 * 175 * Available since API level 29. 176 * 177 * \param serviceSpecific an implementation defined error code. 178 * 179 * \return a newly constructed status object that the caller owns. 180 */ 181 __attribute__((warn_unused_result)) AStatus* AStatus_fromServiceSpecificError( 182 int32_t serviceSpecific) __INTRODUCED_IN(29); 183 184 /** 185 * New status with a service specific error and message. 186 * 187 * This is considered to be EX_TRANSACTION_FAILED with extra information. 188 * 189 * Available since API level 29. 190 * 191 * \param serviceSpecific an implementation defined error code. 192 * \param message the error message to associate with this status object. 193 * 194 * \return a newly constructed status object that the caller owns. 195 */ 196 __attribute__((warn_unused_result)) AStatus* AStatus_fromServiceSpecificErrorWithMessage( 197 int32_t serviceSpecific, const char* message) __INTRODUCED_IN(29); 198 199 /** 200 * New status with binder_status_t. This is typically for low level failures when a binder_status_t 201 * is returned by an API on AIBinder or AParcel, and that is to be returned from a method returning 202 * an AStatus instance. This is the least preferable way to return errors. 203 * Prefer exceptions (particularly service-specific errors) when possible. 204 * 205 * Available since API level 29. 206 * 207 * \param status a low-level error to associate with this status object. 208 * 209 * \return a newly constructed status object that the caller owns. 210 */ 211 __attribute__((warn_unused_result)) AStatus* AStatus_fromStatus(binder_status_t status) 212 __INTRODUCED_IN(29); 213 214 /** 215 * Whether this object represents a successful transaction. If this function returns true, then 216 * AStatus_getExceptionCode will return EX_NONE. 217 * 218 * Available since API level 29. 219 * 220 * \param status the status being queried. 221 * 222 * \return whether the status represents a successful transaction. For more details, see below. 223 */ 224 bool AStatus_isOk(const AStatus* status) __INTRODUCED_IN(29); 225 226 /** 227 * The exception that this status object represents. 228 * 229 * Available since API level 29. 230 * 231 * \param status the status being queried. 232 * 233 * \return the exception code that this object represents. 234 */ 235 binder_exception_t AStatus_getExceptionCode(const AStatus* status) __INTRODUCED_IN(29); 236 237 /** 238 * The service specific error if this object represents one. This function will only ever return a 239 * non-zero result if AStatus_getExceptionCode returns EX_SERVICE_SPECIFIC. If this function returns 240 * 0, the status object may still represent a different exception or status. To find out if this 241 * transaction as a whole is okay, use AStatus_isOk instead. 242 * 243 * Available since API level 29. 244 * 245 * \param status the status being queried. 246 * 247 * \return the service-specific error code if the exception code is EX_SERVICE_SPECIFIC or 0. 248 */ 249 int32_t AStatus_getServiceSpecificError(const AStatus* status) __INTRODUCED_IN(29); 250 251 /** 252 * The status if this object represents one. This function will only ever return a non-zero result 253 * if AStatus_getExceptionCode returns EX_TRANSACTION_FAILED. If this function return 0, the status 254 * object may represent a different exception or a service specific error. To find out if this 255 * transaction as a whole is okay, use AStatus_isOk instead. 256 * 257 * Available since API level 29. 258 * 259 * \param status the status being queried. 260 * 261 * \return the status code if the exception code is EX_TRANSACTION_FAILED or 0. 262 */ 263 binder_status_t AStatus_getStatus(const AStatus* status) __INTRODUCED_IN(29); 264 265 /** 266 * If there is a message associated with this status, this will return that message. If there is no 267 * message, this will return an empty string. 268 * 269 * The returned string has the lifetime of the status object passed into this function. 270 * 271 * Available since API level 29. 272 * 273 * \param status the status being queried. 274 * 275 * \return the message associated with this error. 276 */ 277 const char* AStatus_getMessage(const AStatus* status) __INTRODUCED_IN(29); 278 279 /** 280 * Get human-readable description for debugging. 281 * 282 * Available since API level 30. 283 * 284 * \param status the status being queried. 285 * 286 * \return a description, must be deleted with AStatus_deleteDescription. 287 */ 288 __attribute__((warn_unused_result)) const char* AStatus_getDescription(const AStatus* status) 289 __INTRODUCED_IN(30); 290 291 /** 292 * Delete description. 293 * 294 * \param description value from AStatus_getDescription 295 */ 296 void AStatus_deleteDescription(const char* description) __INTRODUCED_IN(30); 297 298 /** 299 * Deletes memory associated with the status instance. 300 * 301 * Available since API level 29. 302 * 303 * \param status the status to delete, returned from AStatus_newOk or one of the AStatus_from* APIs. 304 */ 305 void AStatus_delete(AStatus* status) __INTRODUCED_IN(29); 306 307 __END_DECLS 308 309 /** @} */ 310