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_BINDER_STATUS_H
18#define ANDROID_BINDER_STATUS_H
19
20#include <cstdint>
21#include <sstream>
22
23#include <binder/Parcel.h>
24#include <utils/String8.h>
25
26namespace android {
27namespace binder {
28
29// An object similar in function to a status_t except that it understands
30// how exceptions are encoded in the prefix of a Parcel. Used like:
31//
32//     Parcel data;
33//     Parcel reply;
34//     status_t status;
35//     binder::Status remote_exception;
36//     if ((status = data.writeInterfaceToken(interface_descriptor)) != OK ||
37//         (status = data.writeInt32(function_input)) != OK) {
38//         // We failed to write into the memory of our local parcel?
39//     }
40//     if ((status = remote()->transact(transaction, data, &reply)) != OK) {
41//        // Something has gone wrong in the binder driver or libbinder.
42//     }
43//     if ((status = remote_exception.readFromParcel(reply)) != OK) {
44//         // The remote didn't correctly write the exception header to the
45//         // reply.
46//     }
47//     if (!remote_exception.isOk()) {
48//         // The transaction went through correctly, but the remote reported an
49//         // exception during handling.
50//     }
51//
52class Status final {
53public:
54    // Keep the exception codes in sync with android/os/Parcel.java.
55    enum Exception {
56        EX_NONE = 0,
57        EX_SECURITY = -1,
58        EX_BAD_PARCELABLE = -2,
59        EX_ILLEGAL_ARGUMENT = -3,
60        EX_NULL_POINTER = -4,
61        EX_ILLEGAL_STATE = -5,
62        EX_NETWORK_MAIN_THREAD = -6,
63        EX_UNSUPPORTED_OPERATION = -7,
64        EX_SERVICE_SPECIFIC = -8,
65        EX_PARCELABLE = -9,
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
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 String8& message);
89    static Status fromExceptionCode(int32_t exceptionCode,
90                                    const char* message);
91
92    static Status fromServiceSpecificError(int32_t serviceSpecificErrorCode);
93    static Status fromServiceSpecificError(int32_t serviceSpecificErrorCode,
94                                           const String8& message);
95    static Status fromServiceSpecificError(int32_t serviceSpecificErrorCode,
96                                           const char* message);
97
98    static Status fromStatusT(status_t status);
99
100    Status() = default;
101    ~Status() = default;
102
103    // Status objects are copyable and contain just simple data.
104    Status(const Status& status) = default;
105    Status(Status&& status) = default;
106    Status& operator=(const Status& status) = default;
107
108    // Bear in mind that if the client or service is a Java endpoint, this
109    // is not the logic which will provide/interpret the data here.
110    status_t readFromParcel(const Parcel& parcel);
111    status_t writeToParcel(Parcel* parcel) const;
112
113    // Set one of the pre-defined exception types defined above.
114    void setException(int32_t ex, const String8& message);
115    // Set a service specific exception with error code.
116    void setServiceSpecificError(int32_t errorCode, const String8& message);
117    // Setting a |status| != OK causes generated code to return |status|
118    // from Binder transactions, rather than writing an exception into the
119    // reply Parcel.  This is the least preferable way of reporting errors.
120    void setFromStatusT(status_t status);
121
122    // Get information about an exception.
123    int32_t exceptionCode() const  { return mException; }
124    const String8& exceptionMessage() const { return mMessage; }
125    status_t transactionError() const {
126        return mException == EX_TRANSACTION_FAILED ? mErrorCode : OK;
127    }
128    int32_t serviceSpecificErrorCode() const {
129        return mException == EX_SERVICE_SPECIFIC ? mErrorCode : 0;
130    }
131
132    bool isOk() const { return mException == EX_NONE; }
133
134    // For logging.
135    String8 toString8() const;
136
137private:
138    Status(int32_t exceptionCode, int32_t errorCode);
139    Status(int32_t exceptionCode, int32_t errorCode, const String8& message);
140
141    // If |mException| == EX_TRANSACTION_FAILED, generated code will return
142    // |mErrorCode| as the result of the transaction rather than write an
143    // exception to the reply parcel.
144    //
145    // Otherwise, we always write |mException| to the parcel.
146    // If |mException| !=  EX_NONE, we write |mMessage| as well.
147    // If |mException| == EX_SERVICE_SPECIFIC we write |mErrorCode| as well.
148    int32_t mException = EX_NONE;
149    int32_t mErrorCode = 0;
150    String8 mMessage;
151};  // class Status
152
153// For gtest output logging
154std::stringstream& operator<< (std::stringstream& stream, const Status& s);
155
156}  // namespace binder
157}  // namespace android
158
159#endif // ANDROID_BINDER_STATUS_H
160