Status.h revision 78039670bc4061f062bfc4e7d2c9682257d99fc8 
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        EX_SERVICE_SPECIFIC = -8,
67
68        // This is special and Java specific; see Parcel.java.
69        EX_HAS_REPLY_HEADER = -128,
70        // This is special, and indicates to C++ binder proxies that the
71        // transaction has failed at a low level.
72        EX_TRANSACTION_FAILED = -129,
73    };
74
75    // A more readable alias for the default constructor.
76    static Status ok();
77    // Authors should explicitly pick whether their integer is:
78    //  - an exception code (EX_* above)
79    //  - service specific error code
80    //  - status_t
81    //
82    //  Prefer a generic exception code when possible, then a service specific
83    //  code, and finally a status_t for low level failures or legacy support.
84    //  Exception codes and service specific errors map to nicer exceptions for
85    //  Java clients.
86    static Status fromExceptionCode(int32_t exceptionCode);
87    static Status fromExceptionCode(int32_t exceptionCode,
88                                    const char *message);
89    static Status fromServiceSpecificError(int32_t serviceSpecificErrorCode);
90    static Status fromServiceSpecificError(int32_t serviceSpecificErrorCode,
91                                           const char *message);
92    static Status fromStatusT(status_t status);
93
94    Status() = default;
95    ~Status() = default;
96
97    // Status objects are copyable and contain just simple data.
98    Status(const Status& status) = default;
99    Status(Status&& status) = default;
100    Status& operator=(const Status& status) = default;
101
102    // Set one of the pre-defined exception types defined above.
103    void setException(int32_t ex, const char *message);
104    // Set a service specific exception with error code.
105    void setServiceSpecificError(int32_t errorCode, const char *message);
106    // Setting a |status| != OK causes generated code to return |status|
107    // from Binder transactions, rather than writing an exception into the
108    // reply Parcel.  This is the least preferable way of reporting errors.
109    void setFromStatusT(status_t status);
110
111    // Get information about an exception.
112    int32_t exceptionCode() const  { return mException; }
113    const char *exceptionMessage() const { return mMessage.c_str(); }
114    status_t transactionError() const {
115        return mException == EX_TRANSACTION_FAILED ? mErrorCode : OK;
116    }
117    int32_t serviceSpecificErrorCode() const {
118        return mException == EX_SERVICE_SPECIFIC ? mErrorCode : 0;
119    }
120
121    bool isOk() const { return mException == EX_NONE; }
122
123    // For debugging purposes only
124    std::string description() const;
125
126private:
127    Status(int32_t exceptionCode, int32_t errorCode);
128    Status(int32_t exceptionCode, int32_t errorCode, const char *message);
129
130    // If |mException| == EX_TRANSACTION_FAILED, generated code will return
131    // |mErrorCode| as the result of the transaction rather than write an
132    // exception to the reply parcel.
133    //
134    // Otherwise, we always write |mException| to the parcel.
135    // If |mException| !=  EX_NONE, we write |mMessage| as well.
136    // If |mException| == EX_SERVICE_SPECIFIC we write |mErrorCode| as well.
137    int32_t mException = EX_NONE;
138    int32_t mErrorCode = 0;
139    std::string mMessage;
140};  // class Status
141
142// For gtest output logging
143std::ostream& operator<< (std::ostream& stream, const Status& s);
144
145namespace details {
146    class return_status : public details::hidl_log_base {
147    private:
148        Status mStatus {};
149        mutable bool mCheckedStatus = false;
150    protected:
151        void checkStatus() const {
152            if (!isOk()) {
153                logAlwaysFatal("Attempted to retrieve value from hidl service, "
154                               "but there was a transport error.");
155            }
156        }
157    public:
158        return_status() {}
159        return_status(Status s) : mStatus(s) {}
160
161        return_status(const return_status &) = default;
162
163        ~return_status() {
164            // mCheckedStatus must be checked before isOk since isOk modifies mCheckedStatus
165            if (!mCheckedStatus && !isOk()) {
166                logAlwaysFatal("HIDL return status not checked and transport error occured.");
167            }
168        }
169
170        bool isOk() const {
171            mCheckedStatus = true;
172            return mStatus.isOk();
173        }
174
175        // TODO(b/31348667) deprecate and replace with 'string description()'
176        const Status& getStatus() const {
177            mCheckedStatus = true;
178            return mStatus;
179        }
180
181        // For debugging purposes only
182        std::string description() const {
183            // Doesn't consider checked.
184            return mStatus.description();
185        }
186    };
187}  // namespace details
188
189template<typename T> class Return : public details::return_status {
190private:
191    T mVal {};
192public:
193    Return(T v) : details::return_status(), mVal{v} {}
194    Return(Status s) : details::return_status(s) {}
195
196    Return(const Return &) = default;
197
198    ~Return() = default;
199
200    operator T() const {
201        checkStatus();
202        return mVal;
203    }
204
205};
206
207template<typename T> class Return<sp<T>> : public details::return_status {
208private:
209    sp<T> mVal {};
210public:
211    Return(sp<T> v) : details::return_status(), mVal{v} {}
212    Return(T* v) : details::return_status(), mVal{v} {}
213    // Constructors matching a different type (that is related by inheritance)
214    template<typename U> Return(sp<U> v) : details::return_status(), mVal{v} {}
215    template<typename U> Return(U* v) : details::return_status(), mVal{v} {}
216    Return(Status s) : details::return_status(s) {}
217
218    Return(const Return &) = default;
219    ~Return() = default;
220
221    operator sp<T>() const {
222        checkStatus();
223        return mVal;
224    }
225};
226
227
228template<> class Return<void> : public details::return_status {
229public:
230    Return() : details::return_status() {}
231    Return(Status s) : details::return_status(s) {}
232
233    Return(const Return &) = default;
234
235    ~Return() = default;
236};
237
238static inline Return<void> Void() {
239    return Return<void>();
240}
241
242}  // namespace hardware
243}  // namespace android
244
245#endif // ANDROID_HARDWARE_BINDER_STATUS_H
246