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__ >= __ANDROID_API_Q__ 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 * \return a newly constructed status object that the caller owns. 109 */ 110 __attribute__((warn_unused_result)) AStatus* AStatus_newOk() __INTRODUCED_IN(29); 111 112 /** 113 * New status with exception code. 114 * 115 * \param exception the code that this status should represent. If this is EX_NONE, then this 116 * constructs an non-error status object. 117 * 118 * \return a newly constructed status object that the caller owns. 119 */ 120 __attribute__((warn_unused_result)) AStatus* AStatus_fromExceptionCode(binder_exception_t exception) 121 __INTRODUCED_IN(29); 122 123 /** 124 * New status with exception code and message. 125 * 126 * \param exception the code that this status should represent. If this is EX_NONE, then this 127 * constructs an non-error status object. 128 * \param message the error message to associate with this status object. 129 * 130 * \return a newly constructed status object that the caller owns. 131 */ 132 __attribute__((warn_unused_result)) AStatus* AStatus_fromExceptionCodeWithMessage( 133 binder_exception_t exception, const char* message) __INTRODUCED_IN(29); 134 135 /** 136 * New status with a service speciic error. 137 * 138 * This is considered to be EX_TRANSACTION_FAILED with extra information. 139 * 140 * \param serviceSpecific an implementation defined error code. 141 * 142 * \return a newly constructed status object that the caller owns. 143 */ 144 __attribute__((warn_unused_result)) AStatus* AStatus_fromServiceSpecificError( 145 int32_t serviceSpecific) __INTRODUCED_IN(29); 146 147 /** 148 * New status with a service specific error and message. 149 * 150 * This is considered to be EX_TRANSACTION_FAILED with extra information. 151 * 152 * \param serviceSpecific an implementation defined error code. 153 * \param message the error message to associate with this status object. 154 * 155 * \return a newly constructed status object that the caller owns. 156 */ 157 __attribute__((warn_unused_result)) AStatus* AStatus_fromServiceSpecificErrorWithMessage( 158 int32_t serviceSpecific, const char* message) __INTRODUCED_IN(29); 159 160 /** 161 * New status with binder_status_t. This is typically for low level failures when a binder_status_t 162 * is returned by an API on AIBinder or AParcel, and that is to be returned from a method returning 163 * an AStatus instance. 164 * 165 * \param a low-level error to associate with this status object. 166 * 167 * \return a newly constructed status object that the caller owns. 168 */ 169 __attribute__((warn_unused_result)) AStatus* AStatus_fromStatus(binder_status_t status) 170 __INTRODUCED_IN(29); 171 172 /** 173 * Whether this object represents a successful transaction. If this function returns true, then 174 * AStatus_getExceptionCode will return EX_NONE. 175 * 176 * \param status the status being queried. 177 * 178 * \return whether the status represents a successful transaction. For more details, see below. 179 */ 180 bool AStatus_isOk(const AStatus* status) __INTRODUCED_IN(29); 181 182 /** 183 * The exception that this status object represents. 184 * 185 * \param status the status being queried. 186 * 187 * \return the exception code that this object represents. 188 */ 189 binder_exception_t AStatus_getExceptionCode(const AStatus* status) __INTRODUCED_IN(29); 190 191 /** 192 * The service specific error if this object represents one. This function will only ever return a 193 * non-zero result if AStatus_getExceptionCode returns EX_SERVICE_SPECIFIC. If this function returns 194 * 0, the status object may still represent a different exception or status. To find out if this 195 * transaction as a whole is okay, use AStatus_isOk instead. 196 * 197 * \param status the status being queried. 198 * 199 * \return the service-specific error code if the exception code is EX_SERVICE_SPECIFIC or 0. 200 */ 201 int32_t AStatus_getServiceSpecificError(const AStatus* status) __INTRODUCED_IN(29); 202 203 /** 204 * The status if this object represents one. This function will only ever return a non-zero result 205 * if AStatus_getExceptionCode returns EX_TRANSACTION_FAILED. If this function return 0, the status 206 * object may represent a different exception or a service specific error. To find out if this 207 * transaction as a whole is okay, use AStatus_isOk instead. 208 * 209 * \param status the status being queried. 210 * 211 * \return the status code if the exception code is EX_TRANSACTION_FAILED or 0. 212 */ 213 binder_status_t AStatus_getStatus(const AStatus* status) __INTRODUCED_IN(29); 214 215 /** 216 * If there is a message associated with this status, this will return that message. If there is no 217 * message, this will return an empty string. 218 * 219 * The returned string has the lifetime of the status object passed into this function. 220 * 221 * \param status the status being queried. 222 * 223 * \return the message associated with this error. 224 */ 225 const char* AStatus_getMessage(const AStatus* status) __INTRODUCED_IN(29); 226 227 /** 228 * Deletes memory associated with the status instance. 229 * 230 * \param status the status to delete, returned from AStatus_newOk or one of the AStatus_from* APIs. 231 */ 232 void AStatus_delete(AStatus* status) __INTRODUCED_IN(29); 233 234 #endif //__ANDROID_API__ >= __ANDROID_API_Q__ 235 __END_DECLS 236 237 /** @} */ 238