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