base/include/hidl/Status.h - platform/system/libhidl - Git at Google

 /*
  * Copyright (C) 2015 The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 #ifndef ANDROID_HARDWARE_BINDER_STATUS_H
 #define ANDROID_HARDWARE_BINDER_STATUS_H

 #include <cstdint>
 #include <sstream>

 #include <hidl/HidlInternal.h>
 #include <utils/Errors.h>
 #include <utils/StrongPointer.h>

 namespace android {
 namespace hardware {

 // An object similar in function to a status_t except that it understands
 // how exceptions are encoded in the prefix of a Parcel. Used like:
 //
 //     Parcel data;
 //     Parcel reply;
 //     status_t status;
 //     binder::Status remote_exception;
 //     if ((status = data.writeInterfaceToken(interface_descriptor)) != OK ||
 //         (status = data.writeInt32(function_input)) != OK) {
 //         // We failed to write into the memory of our local parcel?
 //     }
 //     if ((status = remote()->transact(transaction, data, &reply)) != OK) {
 //        // Something has gone wrong in the binder driver or libbinder.
 //     }
 //     if ((status = remote_exception.readFromParcel(reply)) != OK) {
 //         // The remote didn't correctly write the exception header to the
 //         // reply.
 //     }
 //     if (!remote_exception.isOk()) {
 //         // The transaction went through correctly, but the remote reported an
 //         // exception during handling.
 //     }
 //
 class Status final {
 public:
     // Keep the exception codes in sync with android/os/Parcel.java.
     enum Exception {
         EX_NONE = 0,
         EX_SECURITY = -1,
         EX_BAD_PARCELABLE = -2,
         EX_ILLEGAL_ARGUMENT = -3,
         EX_NULL_POINTER = -4,
         EX_ILLEGAL_STATE = -5,
         EX_NETWORK_MAIN_THREAD = -6,
         EX_UNSUPPORTED_OPERATION = -7,

         // This is special and Java specific; see Parcel.java.
         EX_HAS_REPLY_HEADER = -128,
         // This is special, and indicates to C++ binder proxies that the
         // transaction has failed at a low level.
         EX_TRANSACTION_FAILED = -129,
     };

     // A more readable alias for the default constructor.
     static Status ok();
     // Authors should explicitly pick whether their integer is:
     //  - an exception code (EX_* above)
     //  - status_t
     //
     // Prefer a generic exception code when possible or a status_t
     // for low level transport errors. Service specific errors
     // should be at a higher level in HIDL.
     static Status fromExceptionCode(int32_t exceptionCode);
     static Status fromExceptionCode(int32_t exceptionCode,
                                     const char *message);
     static Status fromStatusT(status_t status);

     Status() = default;
     ~Status() = default;

     // Status objects are copyable and contain just simple data.
     Status(const Status& status) = default;
     Status(Status&& status) = default;
     Status& operator=(const Status& status) = default;

     // Set one of the pre-defined exception types defined above.
     void setException(int32_t ex, const char *message);
     // Setting a |status| != OK causes generated code to return |status|
     // from Binder transactions, rather than writing an exception into the
     // reply Parcel.  This is the least preferable way of reporting errors.
     void setFromStatusT(status_t status);

     // Get information about an exception.
     int32_t exceptionCode() const  { return mException; }
     const char *exceptionMessage() const { return mMessage.c_str(); }
     status_t transactionError() const {
         return mException == EX_TRANSACTION_FAILED ? mErrorCode : OK;
     }

     bool isOk() const { return mException == EX_NONE; }

     // For debugging purposes only
     std::string description() const;

 private:
     Status(int32_t exceptionCode, int32_t errorCode);
     Status(int32_t exceptionCode, int32_t errorCode, const char *message);

     // If |mException| == EX_TRANSACTION_FAILED, generated code will return
     // |mErrorCode| as the result of the transaction rather than write an
     // exception to the reply parcel.
     //
     // Otherwise, we always write |mException| to the parcel.
     // If |mException| !=  EX_NONE, we write |mMessage| as well.
     int32_t mException = EX_NONE;
     int32_t mErrorCode = 0;
     std::string mMessage;
 };  // class Status

 // For gtest output logging
 std::ostream& operator<< (std::ostream& stream, const Status& s);

 template<typename T> class Return;

 namespace details {
     class return_status {
     private:
         Status mStatus {};
         mutable bool mCheckedStatus = false;

         template <typename T, typename U>
         friend Return<U> StatusOf(const Return<T> &other);
     protected:
         void assertOk() const;
     public:
         return_status() {}
         return_status(const Status& s) : mStatus(s) {}

         return_status(const return_status &) = delete;
         return_status &operator=(const return_status &) = delete;

         return_status(return_status &&other) {
             *this = std::move(other);
         }
         return_status &operator=(return_status &&other);

         ~return_status();

         bool isOkUnchecked() const {
             // someone else will have to check
             return mStatus.isOk();
         }

         bool isOk() const {
             mCheckedStatus = true;
             return mStatus.isOk();
         }

         // Check if underlying error is DEAD_OBJECT.
         // Check mCheckedStatus only if this method returns true.
         bool isDeadObject() const {
             bool dead = mStatus.transactionError() == DEAD_OBJECT;

             // This way, if you only check isDeadObject your process will
             // only be killed for more serious unchecked errors
             if (dead) {
                 mCheckedStatus = true;
             }

             return dead;
         }

         // For debugging purposes only
         std::string description() const {
             // Doesn't consider checked.
             return mStatus.description();
         }
     };
 }  // namespace details

 template<typename T> class Return : public details::return_status {
 private:
     T mVal {};
 public:
     Return(T v) : details::return_status(), mVal{v} {}
     Return(Status s) : details::return_status(s) {}

     // move-able.
     // precondition: "this" has checked status
     // postcondition: other is safe to destroy after moving to *this.
     Return(Return &&other) = default;
     Return &operator=(Return &&) = default;

     ~Return() = default;

     operator T() const {
         assertOk();
         return mVal;
     }

     T withDefault(T t) {
         return isOk() ? mVal : t;
     }
 };

 template<typename T> class Return<sp<T>> : public details::return_status {
 private:
     sp<T> mVal {};
 public:
     Return(sp<T> v) : details::return_status(), mVal{v} {}
     Return(T* v) : details::return_status(), mVal{v} {}
     // Constructors matching a different type (that is related by inheritance)
     template<typename U> Return(sp<U> v) : details::return_status(), mVal{v} {}
     template<typename U> Return(U* v) : details::return_status(), mVal{v} {}
     Return(Status s) : details::return_status(s) {}

     // move-able.
     // precondition: "this" has checked status
     // postcondition: other is safe to destroy after moving to *this.
     Return(Return &&other) = default;
     Return &operator=(Return &&) = default;

     ~Return() = default;

     operator sp<T>() const {
         assertOk();
         return mVal;
     }

     sp<T> withDefault(sp<T> t) {
         return isOk() ? mVal : t;
     }
 };


 template<> class Return<void> : public details::return_status {
 public:
     Return() : details::return_status() {}
     Return(const Status& s) : details::return_status(s) {}

     // move-able.
     // precondition: "this" has checked status
     // postcondition: other is safe to destroy after moving to *this.
     Return(Return &&) = default;
     Return &operator=(Return &&) = default;

     ~Return() = default;
 };

 static inline Return<void> Void() {
     return Return<void>();
 }

 namespace details {
 // Create a Return<U> from the Status of Return<T>. The provided
 // Return<T> must have an error status and have it checked.
 template <typename T, typename U>
 Return<U> StatusOf(const Return<T> &other) {
     if (other.mStatus.isOk() || !other.mCheckedStatus) {
         details::logAlwaysFatal("cannot call statusOf on an OK Status or an unchecked status");
     }
     return Return<U>{other.mStatus};
 }
 }  // namespace details

 }  // namespace hardware
 }  // namespace android

 #endif // ANDROID_HARDWARE_BINDER_STATUS_H
	/*
	* Copyright (C) 2015 The Android Open Source Project
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	#ifndef ANDROID_HARDWARE_BINDER_STATUS_H
	#define ANDROID_HARDWARE_BINDER_STATUS_H

	#include <cstdint>
	#include <sstream>

	#include <hidl/HidlInternal.h>
	#include <utils/Errors.h>
	#include <utils/StrongPointer.h>

	namespace android {
	namespace hardware {

	// An object similar in function to a status_t except that it understands
	// how exceptions are encoded in the prefix of a Parcel. Used like:
	//
	// Parcel data;
	// Parcel reply;
	// status_t status;
	// binder::Status remote_exception;
	// if ((status = data.writeInterfaceToken(interface_descriptor)) != OK \|\|
	// (status = data.writeInt32(function_input)) != OK) {
	// // We failed to write into the memory of our local parcel?
	// }
	// if ((status = remote()->transact(transaction, data, &reply)) != OK) {
	// // Something has gone wrong in the binder driver or libbinder.
	// }
	// if ((status = remote_exception.readFromParcel(reply)) != OK) {
	// // The remote didn't correctly write the exception header to the
	// // reply.
	// }
	// if (!remote_exception.isOk()) {
	// // The transaction went through correctly, but the remote reported an
	// // exception during handling.
	// }
	//
	class Status final {
	public:
	// Keep the exception codes in sync with android/os/Parcel.java.
	enum Exception {
	EX_NONE = 0,
	EX_SECURITY = -1,
	EX_BAD_PARCELABLE = -2,
	EX_ILLEGAL_ARGUMENT = -3,
	EX_NULL_POINTER = -4,
	EX_ILLEGAL_STATE = -5,
	EX_NETWORK_MAIN_THREAD = -6,
	EX_UNSUPPORTED_OPERATION = -7,

	// This is special and Java specific; see Parcel.java.
	EX_HAS_REPLY_HEADER = -128,
	// This is special, and indicates to C++ binder proxies that the
	// transaction has failed at a low level.
	EX_TRANSACTION_FAILED = -129,
	};

	// A more readable alias for the default constructor.
	static Status ok();
	// Authors should explicitly pick whether their integer is:
	// - an exception code (EX_* above)
	// - status_t
	//
	// Prefer a generic exception code when possible or a status_t
	// for low level transport errors. Service specific errors
	// should be at a higher level in HIDL.
	static Status fromExceptionCode(int32_t exceptionCode);
	static Status fromExceptionCode(int32_t exceptionCode,
	const char *message);
	static Status fromStatusT(status_t status);

	Status() = default;
	~Status() = default;

	// Status objects are copyable and contain just simple data.
	Status(const Status& status) = default;
	Status(Status&& status) = default;
	Status& operator=(const Status& status) = default;

	// Set one of the pre-defined exception types defined above.
	void setException(int32_t ex, const char *message);
	// Setting a \|status\| != OK causes generated code to return \|status\|
	// from Binder transactions, rather than writing an exception into the
	// reply Parcel. This is the least preferable way of reporting errors.
	void setFromStatusT(status_t status);

	// Get information about an exception.
	int32_t exceptionCode() const { return mException; }
	const char *exceptionMessage() const { return mMessage.c_str(); }
	status_t transactionError() const {
	return mException == EX_TRANSACTION_FAILED ? mErrorCode : OK;
	}

	bool isOk() const { return mException == EX_NONE; }

	// For debugging purposes only
	std::string description() const;

	private:
	Status(int32_t exceptionCode, int32_t errorCode);
	Status(int32_t exceptionCode, int32_t errorCode, const char *message);

	// If \|mException\| == EX_TRANSACTION_FAILED, generated code will return
	// \|mErrorCode\| as the result of the transaction rather than write an
	// exception to the reply parcel.
	//
	// Otherwise, we always write \|mException\| to the parcel.
	// If \|mException\| != EX_NONE, we write \|mMessage\| as well.
	int32_t mException = EX_NONE;
	int32_t mErrorCode = 0;
	std::string mMessage;
	}; // class Status

	// For gtest output logging
	std::ostream& operator<< (std::ostream& stream, const Status& s);

	template<typename T> class Return;

	namespace details {
	class return_status {
	private:
	Status mStatus {};
	mutable bool mCheckedStatus = false;

	template <typename T, typename U>
	friend Return<U> StatusOf(const Return<T> &other);
	protected:
	void assertOk() const;
	public:
	return_status() {}
	return_status(const Status& s) : mStatus(s) {}

	return_status(const return_status &) = delete;
	return_status &operator=(const return_status &) = delete;

	return_status(return_status &&other) {
	*this = std::move(other);
	}
	return_status &operator=(return_status &&other);

	~return_status();

	bool isOkUnchecked() const {
	// someone else will have to check
	return mStatus.isOk();
	}

	bool isOk() const {
	mCheckedStatus = true;
	return mStatus.isOk();
	}

	// Check if underlying error is DEAD_OBJECT.
	// Check mCheckedStatus only if this method returns true.
	bool isDeadObject() const {
	bool dead = mStatus.transactionError() == DEAD_OBJECT;

	// This way, if you only check isDeadObject your process will
	// only be killed for more serious unchecked errors
	if (dead) {
	mCheckedStatus = true;
	}

	return dead;
	}

	// For debugging purposes only
	std::string description() const {
	// Doesn't consider checked.
	return mStatus.description();
	}
	};
	} // namespace details

	template<typename T> class Return : public details::return_status {
	private:
	T mVal {};
	public:
	Return(T v) : details::return_status(), mVal{v} {}
	Return(Status s) : details::return_status(s) {}

	// move-able.
	// precondition: "this" has checked status
	// postcondition: other is safe to destroy after moving to *this.
	Return(Return &&other) = default;
	Return &operator=(Return &&) = default;

	~Return() = default;

	operator T() const {
	assertOk();
	return mVal;
	}

	T withDefault(T t) {
	return isOk() ? mVal : t;
	}
	};

	template<typename T> class Return<sp<T>> : public details::return_status {
	private:
	sp<T> mVal {};
	public:
	Return(sp<T> v) : details::return_status(), mVal{v} {}
	Return(T* v) : details::return_status(), mVal{v} {}
	// Constructors matching a different type (that is related by inheritance)
	template<typename U> Return(sp<U> v) : details::return_status(), mVal{v} {}
	template<typename U> Return(U* v) : details::return_status(), mVal{v} {}
	Return(Status s) : details::return_status(s) {}

	// move-able.
	// precondition: "this" has checked status
	// postcondition: other is safe to destroy after moving to *this.
	Return(Return &&other) = default;
	Return &operator=(Return &&) = default;

	~Return() = default;

	operator sp<T>() const {
	assertOk();
	return mVal;
	}

	sp<T> withDefault(sp<T> t) {
	return isOk() ? mVal : t;
	}
	};


	template<> class Return<void> : public details::return_status {
	public:
	Return() : details::return_status() {}
	Return(const Status& s) : details::return_status(s) {}

	// move-able.
	// precondition: "this" has checked status
	// postcondition: other is safe to destroy after moving to *this.
	Return(Return &&) = default;
	Return &operator=(Return &&) = default;

	~Return() = default;
	};

	static inline Return<void> Void() {
	return Return<void>();
	}

	namespace details {
	// Create a Return<U> from the Status of Return<T>. The provided
	// Return<T> must have an error status and have it checked.
	template <typename T, typename U>
	Return<U> StatusOf(const Return<T> &other) {
	if (other.mStatus.isOk() \|\| !other.mCheckedStatus) {
	details::logAlwaysFatal("cannot call statusOf on an OK Status or an unchecked status");
	}
	return Return<U>{other.mStatus};
	}
	} // namespace details

	} // namespace hardware
	} // namespace android

	#endif // ANDROID_HARDWARE_BINDER_STATUS_H