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