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