Status/Return: document expected usage. am: 779a714661
am: 1a767d32b4
Change-Id: Ia7e0c8ce845c095f5baf64b0149a9889f24ab437
diff --git a/base/include/hidl/Status.h b/base/include/hidl/Status.h
index b69d4e4..765f0f7 100644
--- a/base/include/hidl/Status.h
+++ b/base/include/hidl/Status.h
@@ -27,32 +27,36 @@
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:
+// HIDL formally separates transport error codes from interface error codes. When developing a HIDL
+// interface, errors relevant to a service should be placed in the interface design for that HAL.
//
-// 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.
-// }
+// For instance:
//
+// interface I* {
+// enum FooStatus { NO_FOO, NO_BAR }; // service-specific errors
+// doFoo(...) generates (FooStatus foo);
+// };
+//
+// When calling into this interface, a Return<*> (in this case Return<FooStatus> object will be
+// returned). For most clients, it's expected that they'll just get the result from this function
+// and use it directly. If there is a transport error, the process will just abort. In general,
+// transport errors are expected only in extremely rare circumstances (bug in the
+// code/cosmic radiation/etc..). Aborting allows process to restart using their normal happy path
+// code.
+//
+// For certain processes though which are critical to the functionality of the phone (e.g.
+// hwservicemanager/init), these errors must be handled. Return<*>::isOk and
+// Return<*>::isDeadObject are provided for these cases. Whenever this is done, special attention
+// should be paid to testing the unhappy paths to make sure that error handling is handled
+// properly.
+
+// Transport implementation detail. HIDL implementors, see Return below. HAL implementations should
+// return HIDL-defined errors rather than use this.
class Status final {
public:
- // Keep the exception codes in sync with android/os/Parcel.java.
+ // Note: forked from
+ // - frameworks/base/core/java/android/os/android/os/Parcel.java.
+ // - frameworks/native/libs/binder/include/binder/Status.h
enum Exception {
EX_NONE = 0,
EX_SECURITY = -1,