Functions

Functions in a HIDL interface are mapped to methods in the autogenerated IFoo C++ class declaration. The name of each function remains the same in C++; the following sections describe how HIDL arguments and return values are translated to C++.

Function parameters

The arguments listed in the .hal file map to C++ data types. Arguments that do not map to a primitive C++ type are passed by const reference.

For every HIDL function that has a return value (has a generates statement), the C++ parameter list for that function has an additional argument: a callback function that is called with the return values of the HIDL function. There is one exception: If the generates clause contains a single parameter that directly maps to a C++ primitive, callback elision is used (the callback is removed and the return value is returned from the function through a normal return statement).

Function return values

The following functions have return values.

Transport errors and return type

The generates statement can result in three types of function signatures:

  • For only one return value that is a C++ primitive, the generates return value is returned by value from the function in a Return<T> object.
  • For more complicated cases, the generates return value(s) are returned through the callback parameter provided with the function call itself, and the function returns Return<void>.
  • For when no generates statement exists, the function returns Return<void>.

RPC calls can occasionally encounter transport errors, e.g. when the server dies, when transport resources are insufficient to complete the call, or when the parameters passed do not permit completing the call (such as missing a required callback function). Return objects store transport error indications as well as a T value (except Return<void>).

As the client-side and server-side functions have the same signature, the server-side function must return a Return type even though its implementation does not signal transport errors. Return<T> objects are constructed with Return(myTValue) (or can be implicitly constructed from mTValue, such as in return statements) and Return<void> objects are constructed with Void().

Return<T> objects have implicit conversion to and from their T value. The Return object can be checked for transport errors by calling its isOk() method. This check is not required; however, if an error occurs and is not checked by the time the Return object is destroyed, or a T value conversion is attempted, the client process will be killed and an error logged. If isOk() indicates a transport error or a call failure due to a logic error in developer code (such as passing nullptr as a synchronous callback), then description() can be called on the Return object to return a string suitable for logging. In such cases, there is no way to determine how much code may have executed on the server as a result of the failed call. The method isDeadObject() is also provided. This method indicates that !isOk() is because the remote object has crashed or no longer exists. isDeadObject() always implies !isOk().

Return by value

If the generates statement maps to a single C++ primitive, no callback parameter is in the parameter list. Instead, an implementation provides the return value T in a Return<T> object, which can be implicitly generated from the primitive type T. For example:

Return<uint32_t> someMethod() {
    uint32_t return_data = ...; // Compute return_data
    return return_data;
};

The method Return<*>::withDefault is also provided. This method provides a value in cases where the return value is !isOk(). This method also automatically marks the return object as okay so the client process will not be killed.

Return using callback parameter

A callback can pass the return value of the HIDL function back to the caller. The prototype of the callback is a std::function object with parameters (taken from the generates statement) mapped to C++ types. Its return value is void—the callback itself doesn't return a value.

The return value of a C++ function with a callback parameter has type Return<void>. The server implementation is responsible only for providing the return value. As the return values are already transferred using the callback, the T template parameter is void: 

Return<void> someMethod(someMethod_cb _cb);

From their C++ implementation, server implementations should return Void(), which is a static inlined function returning a Return<void> object. Example of a typical server method implementation with a callback parameter:

Return<void> someMethod(someMethod_cb _cb) {
    // Do some processing, then call callback with return data
    hidl_vec<uint32_t> vec = ...
    _cb(vec);
    return Void();
};

Functions without return values

The C++ signature of a function without a generates statement will not have a callback parameter in the parameter list. Its return type will be Return<void>.

Oneway functions

Functions marked with the oneway keyword are asynchronous functions (clients won't block on their execution) and do not have return values. The C++ signature of a oneway function will not have a callback parameter in the parameter list, and its C++ return value will be Return<void>.