1 /*
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_HARDWARE_BINDER_STATUS_H
18 #define ANDROID_HARDWARE_BINDER_STATUS_H
19
20 #include <cstdint>
21 #include <sstream>
22
23 #include <hidl/HidlInternal.h>
24 #include <utils/Errors.h>
25 #include <utils/StrongPointer.h>
26
27 namespace android {
28 namespace hardware {
29
30 // An object similar in function to a status_t except that it understands
31 // how exceptions are encoded in the prefix of a Parcel. Used like:
32 //
33 // Parcel data;
34 // Parcel reply;
35 // status_t status;
36 // binder::Status remote_exception;
37 // if ((status = data.writeInterfaceToken(interface_descriptor)) != OK ||
38 // (status = data.writeInt32(function_input)) != OK) {
39 // // We failed to write into the memory of our local parcel?
40 // }
41 // if ((status = remote()->transact(transaction, data, &reply)) != OK) {
42 // // Something has gone wrong in the binder driver or libbinder.
43 // }
44 // if ((status = remote_exception.readFromParcel(reply)) != OK) {
45 // // The remote didn't correctly write the exception header to the
46 // // reply.
47 // }
48 // if (!remote_exception.isOk()) {
49 // // The transaction went through correctly, but the remote reported an
50 // // exception during handling.
51 // }
52 //
53 class Status final {
54 public:
55 // Keep the exception codes in sync with android/os/Parcel.java.
56 enum Exception {
57 EX_NONE = 0,
58 EX_SECURITY = -1,
59 EX_BAD_PARCELABLE = -2,
60 EX_ILLEGAL_ARGUMENT = -3,
61 EX_NULL_POINTER = -4,
62 EX_ILLEGAL_STATE = -5,
63 EX_NETWORK_MAIN_THREAD = -6,
64 EX_UNSUPPORTED_OPERATION = -7,
65
66 // This is special and Java specific; see Parcel.java.
67 EX_HAS_REPLY_HEADER = -128,
68 // This is special, and indicates to C++ binder proxies that the
69 // transaction has failed at a low level.
70 EX_TRANSACTION_FAILED = -129,
71 };
72
73 // A more readable alias for the default constructor.
74 static Status ok();
75 // Authors should explicitly pick whether their integer is:
76 // - an exception code (EX_* above)
77 // - status_t
78 //
79 // Prefer a generic exception code when possible or a status_t
80 // for low level transport errors. Service specific errors
81 // should be at a higher level in HIDL.
82 static Status fromExceptionCode(int32_t exceptionCode);
83 static Status fromExceptionCode(int32_t exceptionCode,
84 const char *message);
85 static Status fromStatusT(status_t status);
86
87 Status() = default;
88 ~Status() = default;
89
90 // Status objects are copyable and contain just simple data.
91 Status(const Status& status) = default;
92 Status(Status&& status) = default;
93 Status& operator=(const Status& status) = default;
94
95 // Set one of the pre-defined exception types defined above.
96 void setException(int32_t ex, const char *message);
97 // Setting a |status| != OK causes generated code to return |status|
98 // from Binder transactions, rather than writing an exception into the
99 // reply Parcel. This is the least preferable way of reporting errors.
100 void setFromStatusT(status_t status);
101
102 // Get information about an exception.
exceptionCode()103 int32_t exceptionCode() const { return mException; }
exceptionMessage()104 const char *exceptionMessage() const { return mMessage.c_str(); }
transactionError()105 status_t transactionError() const {
106 return mException == EX_TRANSACTION_FAILED ? mErrorCode : OK;
107 }
108
isOk()109 bool isOk() const { return mException == EX_NONE; }
110
111 // For debugging purposes only
112 std::string description() const;
113
114 private:
115 Status(int32_t exceptionCode, int32_t errorCode);
116 Status(int32_t exceptionCode, int32_t errorCode, const char *message);
117
118 // If |mException| == EX_TRANSACTION_FAILED, generated code will return
119 // |mErrorCode| as the result of the transaction rather than write an
120 // exception to the reply parcel.
121 //
122 // Otherwise, we always write |mException| to the parcel.
123 // If |mException| != EX_NONE, we write |mMessage| as well.
124 int32_t mException = EX_NONE;
125 int32_t mErrorCode = 0;
126 std::string mMessage;
127 }; // class Status
128
129 // For gtest output logging
130 std::ostream& operator<< (std::ostream& stream, const Status& s);
131
132 template<typename T> class Return;
133
134 namespace details {
135 class return_status {
136 private:
137 Status mStatus {};
138 mutable bool mCheckedStatus = false;
139
140 template <typename T, typename U>
141 friend Return<U> StatusOf(const Return<T> &other);
142 protected:
143 void assertOk() const;
144 public:
return_status()145 return_status() {}
return_status(const Status & s)146 return_status(const Status& s) : mStatus(s) {}
147
148 return_status(const return_status &) = delete;
149 return_status &operator=(const return_status &) = delete;
150
return_status(return_status && other)151 return_status(return_status &&other) {
152 *this = std::move(other);
153 }
154 return_status &operator=(return_status &&other);
155
156 ~return_status();
157
isOkUnchecked()158 bool isOkUnchecked() const {
159 // someone else will have to check
160 return mStatus.isOk();
161 }
162
isOk()163 bool isOk() const {
164 mCheckedStatus = true;
165 return mStatus.isOk();
166 }
167
168 // Check if underlying error is DEAD_OBJECT.
169 // Check mCheckedStatus only if this method returns true.
isDeadObject()170 bool isDeadObject() const {
171 bool dead = mStatus.transactionError() == DEAD_OBJECT;
172
173 // This way, if you only check isDeadObject your process will
174 // only be killed for more serious unchecked errors
175 if (dead) {
176 mCheckedStatus = true;
177 }
178
179 return dead;
180 }
181
182 // For debugging purposes only
description()183 std::string description() const {
184 // Doesn't consider checked.
185 return mStatus.description();
186 }
187 };
188 } // namespace details
189
190 template<typename T> class Return : public details::return_status {
191 private:
192 T mVal {};
193 public:
Return(T v)194 Return(T v) : details::return_status(), mVal{v} {}
Return(Status s)195 Return(Status s) : details::return_status(s) {}
196
197 // move-able.
198 // precondition: "this" has checked status
199 // postcondition: other is safe to destroy after moving to *this.
200 Return(Return &&other) = default;
201 Return &operator=(Return &&) = default;
202
203 ~Return() = default;
204
T()205 operator T() const {
206 assertOk();
207 return mVal;
208 }
209
withDefault(T t)210 T withDefault(T t) {
211 return isOk() ? mVal : t;
212 }
213 };
214
215 template<typename T> class Return<sp<T>> : public details::return_status {
216 private:
217 sp<T> mVal {};
218 public:
Return(sp<T> v)219 Return(sp<T> v) : details::return_status(), mVal{v} {}
Return(T * v)220 Return(T* v) : details::return_status(), mVal{v} {}
221 // Constructors matching a different type (that is related by inheritance)
Return(sp<U> v)222 template<typename U> Return(sp<U> v) : details::return_status(), mVal{v} {}
Return(U * v)223 template<typename U> Return(U* v) : details::return_status(), mVal{v} {}
Return(Status s)224 Return(Status s) : details::return_status(s) {}
225
226 // move-able.
227 // precondition: "this" has checked status
228 // postcondition: other is safe to destroy after moving to *this.
229 Return(Return &&other) = default;
230 Return &operator=(Return &&) = default;
231
232 ~Return() = default;
233
234 operator sp<T>() const {
235 assertOk();
236 return mVal;
237 }
238
withDefault(sp<T> t)239 sp<T> withDefault(sp<T> t) {
240 return isOk() ? mVal : t;
241 }
242 };
243
244
245 template<> class Return<void> : public details::return_status {
246 public:
Return()247 Return() : details::return_status() {}
Return(const Status & s)248 Return(const Status& s) : details::return_status(s) {}
249
250 // move-able.
251 // precondition: "this" has checked status
252 // postcondition: other is safe to destroy after moving to *this.
253 Return(Return &&) = default;
254 Return &operator=(Return &&) = default;
255
256 ~Return() = default;
257 };
258
Void()259 static inline Return<void> Void() {
260 return Return<void>();
261 }
262
263 namespace details {
264 // Create a Return<U> from the Status of Return<T>. The provided
265 // Return<T> must have an error status and have it checked.
266 template <typename T, typename U>
StatusOf(const Return<T> & other)267 Return<U> StatusOf(const Return<T> &other) {
268 if (other.mStatus.isOk() || !other.mCheckedStatus) {
269 details::logAlwaysFatal("cannot call statusOf on an OK Status or an unchecked status");
270 }
271 return Return<U>{other.mStatus};
272 }
273 } // namespace details
274
275 } // namespace hardware
276 } // namespace android
277
278 #endif // ANDROID_HARDWARE_BINDER_STATUS_H
279