Status.h revision 603cde990a56fc03731d9b428d3376dd75936c2e 
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 <utils/Errors.h>
25#include <utils/StrongPointer.h>
26
27namespace android {
28namespace 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//
53class Status final {
54public:
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        EX_SERVICE_SPECIFIC = -8,
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    //  - service specific error code
79    //  - status_t
80    //
81    //  Prefer a generic exception code when possible, then a service specific
82    //  code, and finally a status_t for low level failures or legacy support.
83    //  Exception codes and service specific errors map to nicer exceptions for
84    //  Java clients.
85    static Status fromExceptionCode(int32_t exceptionCode);
86    static Status fromExceptionCode(int32_t exceptionCode,
87                                    const char *message);
88    static Status fromServiceSpecificError(int32_t serviceSpecificErrorCode);
89    static Status fromServiceSpecificError(int32_t serviceSpecificErrorCode,
90                                           const char *message);
91    static Status fromStatusT(status_t status);
92
93    Status() = default;
94    ~Status() = default;
95
96    // Status objects are copyable and contain just simple data.
97    Status(const Status& status) = default;
98    Status(Status&& status) = default;
99    Status& operator=(const Status& status) = default;
100
101    // Set one of the pre-defined exception types defined above.
102    void setException(int32_t ex, const char *message);
103    // Set a service specific exception with error code.
104    void setServiceSpecificError(int32_t errorCode, const char *message);
105    // Setting a |status| != OK causes generated code to return |status|
106    // from Binder transactions, rather than writing an exception into the
107    // reply Parcel.  This is the least preferable way of reporting errors.
108    void setFromStatusT(status_t status);
109
110    // Get information about an exception.
111    int32_t exceptionCode() const  { return mException; }
112    const char *exceptionMessage() const { return mMessage.c_str(); }
113    status_t transactionError() const {
114        return mException == EX_TRANSACTION_FAILED ? mErrorCode : OK;
115    }
116    int32_t serviceSpecificErrorCode() const {
117        return mException == EX_SERVICE_SPECIFIC ? mErrorCode : 0;
118    }
119
120    bool isOk() const { return mException == EX_NONE; }
121
122    // For debugging purposes only
123    std::string description() const;
124
125private:
126    Status(int32_t exceptionCode, int32_t errorCode);
127    Status(int32_t exceptionCode, int32_t errorCode, const char *message);
128
129    // If |mException| == EX_TRANSACTION_FAILED, generated code will return
130    // |mErrorCode| as the result of the transaction rather than write an
131    // exception to the reply parcel.
132    //
133    // Otherwise, we always write |mException| to the parcel.
134    // If |mException| !=  EX_NONE, we write |mMessage| as well.
135    // If |mException| == EX_SERVICE_SPECIFIC we write |mErrorCode| as well.
136    int32_t mException = EX_NONE;
137    int32_t mErrorCode = 0;
138    std::string mMessage;
139};  // class Status
140
141// For gtest output logging
142std::ostream& operator<< (std::ostream& stream, const Status& s);
143
144namespace details {
145    class return_status {
146    private:
147        Status mStatus {};
148        mutable bool mCheckedStatus = false;
149    protected:
150        void checkStatus() const;
151    public:
152        return_status() {}
153        return_status(Status s) : mStatus(s) {}
154
155        return_status(const return_status &) = delete;
156        return_status &operator=(const return_status &) = delete;
157
158        return_status(return_status &&other) {
159            *this = std::move(other);
160        }
161        return_status &operator=(return_status &&other) {
162            checkStatus();
163            std::swap(mStatus, other.mStatus);
164            std::swap(mCheckedStatus, other.mCheckedStatus);
165            return *this;
166        }
167
168        ~return_status();
169
170        bool isOk() const {
171            mCheckedStatus = true;
172            return mStatus.isOk();
173        }
174
175        // For debugging purposes only
176        std::string description() const {
177            // Doesn't consider checked.
178            return mStatus.description();
179        }
180    };
181}  // namespace details
182
183template<typename T> class Return : public details::return_status {
184private:
185    T mVal {};
186public:
187    Return(T v) : details::return_status(), mVal{v} {}
188    Return(Status s) : details::return_status(s) {}
189
190    // move-able.
191    // precondition: "this" has checked status
192    // postcondition: other is safe to destroy after moving to *this.
193    Return(Return &&other) = default;
194    Return &operator=(Return &&) = default;
195
196    ~Return() = default;
197
198    operator T() const {
199        checkStatus();
200        return mVal;
201    }
202
203};
204
205template<typename T> class Return<sp<T>> : public details::return_status {
206private:
207    sp<T> mVal {};
208public:
209    Return(sp<T> v) : details::return_status(), mVal{v} {}
210    Return(T* v) : details::return_status(), mVal{v} {}
211    // Constructors matching a different type (that is related by inheritance)
212    template<typename U> Return(sp<U> v) : details::return_status(), mVal{v} {}
213    template<typename U> Return(U* v) : details::return_status(), mVal{v} {}
214    Return(Status s) : details::return_status(s) {}
215
216    // move-able.
217    // precondition: "this" has checked status
218    // postcondition: other is safe to destroy after moving to *this.
219    Return(Return &&other) = default;
220    Return &operator=(Return &&) = default;
221
222    ~Return() = default;
223
224    operator sp<T>() const {
225        checkStatus();
226        return mVal;
227    }
228};
229
230
231template<> class Return<void> : public details::return_status {
232public:
233    Return() : details::return_status() {}
234    Return(Status s) : details::return_status(s) {}
235
236    // move-able.
237    // precondition: "this" has checked status
238    // postcondition: other is safe to destroy after moving to *this.
239    Return(Return &&) = default;
240    Return &operator=(Return &&) = default;
241
242    ~Return() = default;
243};
244
245static inline Return<void> Void() {
246    return Return<void>();
247}
248
249}  // namespace hardware
250}  // namespace android
251
252#endif // ANDROID_HARDWARE_BINDER_STATUS_H
253