blob: ce947fa3de49052c514269dc72f59e884846b6f2 [file] [log] [blame]
Christopher Wiley09eb7492015-11-09 15:06:15 -08001/*
2 * Copyright (C) 2015 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#ifndef ANDROID_BINDER_STATUS_H
18#define ANDROID_BINDER_STATUS_H
19
20#include <cstdint>
21
22#include <binder/Parcel.h>
23#include <utils/String8.h>
24
25namespace android {
26namespace binder {
27
28// An object similar in function to a status_t except that it understands
29// how exceptions are encoded in the prefix of a Parcel. Used like:
30//
31// Parcel data;
32// Parcel reply;
33// status_t status;
34// binder::Status remote_exception;
35// if ((status = data.writeInterfaceToken(interface_descriptor)) != OK ||
36// (status = data.writeInt32(function_input)) != OK) {
37// // We failed to write into the memory of our local parcel?
38// }
39// if ((status = remote()->transact(transaction, data, &reply)) != OK) {
40// // Something has gone wrong in the binder driver or libbinder.
41// }
42// if ((status = remote_exception.readFromParcel(reply)) != OK) {
43// // The remote didn't correctly write the exception header to the
44// // reply.
45// }
46// if (!remote_exception.isOk()) {
47// // The transaction went through correctly, but the remote reported an
48// // exception during handling.
49// }
50//
51class Status final {
52public:
53 // Keep the exception codes in sync with android/os/Parcel.java.
54 enum Exception {
55 EX_NONE = 0,
56 EX_SECURITY = -1,
57 EX_BAD_PARCELABLE = -2,
58 EX_ILLEGAL_ARGUMENT = -3,
59 EX_NULL_POINTER = -4,
60 EX_ILLEGAL_STATE = -5,
61 EX_NETWORK_MAIN_THREAD = -6,
62 EX_UNSUPPORTED_OPERATION = -7,
Christopher Wileyc1e491d2015-11-20 17:48:27 -080063 EX_SERVICE_SPECIFIC = -8,
Christopher Wiley09eb7492015-11-09 15:06:15 -080064
65 // This is special and Java specific; see Parcel.java.
66 EX_HAS_REPLY_HEADER = -128,
Christopher Wileycff7f172015-11-22 16:29:58 -080067 // This is special, and indicates to C++ binder proxies that the
68 // transaction has failed at a low level.
69 EX_TRANSACTION_FAILED = -129,
Christopher Wiley09eb7492015-11-09 15:06:15 -080070 };
71
Christopher Wiley09eb7492015-11-09 15:06:15 -080072 // A more readable alias for the default constructor.
73 static Status ok();
Christopher Wileyc1e491d2015-11-20 17:48:27 -080074 // Authors should explicitly pick whether their integer is:
75 // - an exception code (EX_* above)
76 // - service specific error code
77 // - status_t
78 //
79 // Prefer a generic exception code when possible, then a service specific
80 // code, and finally a status_t for low level failures or legacy support.
81 // Exception codes and service specific errors map to nicer exceptions for
82 // Java clients.
Christopher Wileycff7f172015-11-22 16:29:58 -080083 static Status fromExceptionCode(int32_t exceptionCode);
84 static Status fromExceptionCode(int32_t exceptionCode,
85 const String8& message);
Christopher Wileyc1e491d2015-11-20 17:48:27 -080086 static Status fromServiceSpecificError(int32_t serviceSpecificErrorCode);
87 static Status fromServiceSpecificError(int32_t serviceSpecificErrorCode,
88 const String8& message);
Christopher Wileycff7f172015-11-22 16:29:58 -080089 static Status fromStatusT(status_t status);
Christopher Wiley09eb7492015-11-09 15:06:15 -080090
91 Status() = default;
Christopher Wileycff7f172015-11-22 16:29:58 -080092 ~Status() = default;
Christopher Wiley09eb7492015-11-09 15:06:15 -080093
94 // Status objects are copyable and contain just simple data.
95 Status(const Status& status) = default;
96 Status(Status&& status) = default;
97 Status& operator=(const Status& status) = default;
98
Christopher Wiley09eb7492015-11-09 15:06:15 -080099 // Bear in mind that if the client or service is a Java endpoint, this
100 // is not the logic which will provide/interpret the data here.
101 status_t readFromParcel(const Parcel& parcel);
102 status_t writeToParcel(Parcel* parcel) const;
103
104 // Set one of the pre-defined exception types defined above.
105 void setException(int32_t ex, const String8& message);
Christopher Wileyc1e491d2015-11-20 17:48:27 -0800106 // Set a service specific exception with error code.
107 void setServiceSpecificError(int32_t errorCode, const String8& message);
Christopher Wileycff7f172015-11-22 16:29:58 -0800108 // Setting a |status| != OK causes generated code to return |status|
109 // from Binder transactions, rather than writing an exception into the
Christopher Wileyc1e491d2015-11-20 17:48:27 -0800110 // reply Parcel. This is the least preferable way of reporting errors.
Christopher Wiley09eb7492015-11-09 15:06:15 -0800111 void setFromStatusT(status_t status);
112
113 // Get information about an exception.
Christopher Wiley09eb7492015-11-09 15:06:15 -0800114 int32_t exceptionCode() const { return mException; }
115 const String8& exceptionMessage() const { return mMessage; }
Christopher Wileycff7f172015-11-22 16:29:58 -0800116 status_t transactionError() const {
117 return mException == EX_TRANSACTION_FAILED ? mErrorCode : OK;
118 }
Christopher Wileyc1e491d2015-11-20 17:48:27 -0800119 int32_t serviceSpecificErrorCode() const {
120 return mException == EX_SERVICE_SPECIFIC ? mErrorCode : 0;
121 }
Christopher Wiley09eb7492015-11-09 15:06:15 -0800122
123 bool isOk() const { return mException == EX_NONE; }
124
125 // For logging.
126 String8 toString8() const;
127
128private:
Christopher Wileyc1e491d2015-11-20 17:48:27 -0800129 Status(int32_t exceptionCode, int32_t errorCode);
130 Status(int32_t exceptionCode, int32_t errorCode, const String8& message);
Christopher Wileycff7f172015-11-22 16:29:58 -0800131
132 // If |mException| == EX_TRANSACTION_FAILED, generated code will return
133 // |mErrorCode| as the result of the transaction rather than write an
134 // exception to the reply parcel.
135 //
136 // Otherwise, we always write |mException| to the parcel.
137 // If |mException| != EX_NONE, we write |mMessage| as well.
Christopher Wileyc1e491d2015-11-20 17:48:27 -0800138 // If |mException| == EX_SERVICE_SPECIFIC we write |mErrorCode| as well.
Christopher Wiley09eb7492015-11-09 15:06:15 -0800139 int32_t mException = EX_NONE;
Christopher Wileycff7f172015-11-22 16:29:58 -0800140 int32_t mErrorCode = 0;
Christopher Wiley09eb7492015-11-09 15:06:15 -0800141 String8 mMessage;
142}; // class Status
143
Eino-Ville Talvalabbab1962016-02-03 13:19:49 -0800144// For gtest output logging
145template<typename T>
146T& operator<< (T& stream, const Status& s) {
147 stream << s.toString8().string();
148 return stream;
149}
150
Christopher Wiley09eb7492015-11-09 15:06:15 -0800151} // namespace binder
152} // namespace android
153
154#endif // ANDROID_BINDER_STATUS_H