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