libs/binder/include/binder/Status.h

   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
  26 namespace android {
  27 namespace 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 //
  52 class Status final {
  53 public:
  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
 137 private:
 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
 154 std::stringstream& operator<< (std::stringstream& stream, const Status& s);
 155
 156 }  // namespace binder
 157 }  // namespace android
 158
 159 #endif // ANDROID_BINDER_STATUS_H