Status.h revision 43298f90efb47e1ae3589df56b12e9e53f16c53e
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 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 : public details::hidl_log_base { 146 private: 147 Status mStatus {}; 148 mutable bool mCheckedStatus = false; 149 public: 150 return_status() {} 151 return_status(Status s) : mStatus(s) {} 152 153 return_status(const return_status &) = default; 154 155 ~return_status() { 156 // mCheckedStatus must be checked before isOk since isOk modifies mCheckedStatus 157 if (!mCheckedStatus && !isOk()) { 158 logAlwaysFatal("HIDL return status not checked and transport error occured."); 159 } 160 } 161 162 bool isOk() const { 163 mCheckedStatus = true; 164 return mStatus.isOk(); 165 } 166 167 // TODO(b/31348667) deprecate and replace with 'string description()' 168 const Status& getStatus() const { 169 mCheckedStatus = true; 170 return mStatus; 171 } 172 173 // For debugging purposes only 174 std::string description() const { 175 // Doesn't consider checked. 176 return mStatus.description(); 177 } 178 }; 179} // namespace details 180 181template<typename T> class Return : public details::return_status { 182private: 183 T mVal {}; 184public: 185 Return(T v) : details::return_status(), mVal{v} {} 186 Return(Status s) : details::return_status(s) {} 187 188 Return(const Return &) = default; 189 190 ~Return() = default; 191 192 operator T() const { 193 if (!isOk()) { 194 logAlwaysFatal("Attempted to retrieve value from hidl service, " 195 "but there was a transport error."); 196 } 197 return mVal; 198 } 199 200}; 201 202template<> class Return<void> : public details::return_status { 203public: 204 Return() : details::return_status() {} 205 Return(Status s) : details::return_status(s) {} 206 207 Return(const Return &) = default; 208 209 ~Return() = default; 210}; 211 212static inline Return<void> Void() { 213 return Return<void>(); 214} 215 216} // namespace hardware 217} // namespace android 218 219#endif // ANDROID_HARDWARE_BINDER_STATUS_H 220