• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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