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