diff options
| author | Android Partner Docs <noreply@android.com> | 2017-08-22 10:41:24 -0700 |
|---|---|---|
| committer | Clay Murphy <claym@google.com> | 2017-08-22 15:01:44 -0700 |
| commit | f16c42333aa6b2de30a344dd68246d4a33d93e7d (patch) | |
| tree | 311af599312cacb21c888aeae828cae59b0d64a1 /en/devices/architecture/hidl-cpp/functions.html | |
| parent | 04426e67ca3ee557a0083f9b3c6ba789021bd7a0 (diff) | |
| download | source.android.com-f16c42333aa6b2de30a344dd68246d4a33d93e7d.tar.gz | |
Docs: Changes to source.android.com
- 166080694 Devsite localized content from translation request a3d5a7... by Android Partner Docs <noreply@android.com>
- 166079245 Remove duplicate TOC entry to oob-users.html. by mheco <mheco@google.com>
- 166002955 Update builds for Oreo by Android Partner Docs <noreply@android.com>
- 165977566 Fixing bad conversion by hvm <hvm@google.com>
- 165977199 Edit links to point to public source files in AOSP. by cqn <cqn@google.com>
- 165962883 Add codename to CTS downloads page. by gdimino <gdimino@google.com>
- 165955117 Integration of O branch into mainline. by gdimino <gdimino@google.com>
- 165638251 Update July public Android security bulletin to remove QC... by Android Partner Docs <noreply@android.com>
- 165638198 Update June public Android security bulletin to remove QC... by Android Partner Docs <noreply@android.com>
- 165638174 Update May public Android security bulletin to remove QC ... by Android Partner Docs <noreply@android.com>
- 165638096 Update April public Android security bulletin to remove Q... by Android Partner Docs <noreply@android.com>
- 165528993 Update to Keymaster 2 and remove requirements language by daroberts <daroberts@google.com>
- 165511119 Add Bluetooth verification / debug information by cqn <cqn@google.com>
- 165491345 Fixed link broken by file rename. by cqn <cqn@google.com>
- 165381648 Fixed broken image paths and renamed HCI Requirements file. by cqn <cqn@google.com>
- 165365185 Created high-level Bluetooth directory and added HTML ver... by cqn <cqn@google.com>
- 165335694 Devsite localized content from translation request 66a39c... by Android Partner Docs <noreply@android.com>
- 165246927 Update August 2017 bulletin with CVE-2017-0687 by daroberts <daroberts@google.com>
PiperOrigin-RevId: 166080694
Change-Id: I2d3a8d77fa6a66c2099f13ba2e864545328fd17a
Diffstat (limited to 'en/devices/architecture/hidl-cpp/functions.html')
| -rw-r--r-- | en/devices/architecture/hidl-cpp/functions.html | 153 |
1 files changed, 153 insertions, 0 deletions
diff --git a/en/devices/architecture/hidl-cpp/functions.html b/en/devices/architecture/hidl-cpp/functions.html new file mode 100644 index 00000000..5d52b31d --- /dev/null +++ b/en/devices/architecture/hidl-cpp/functions.html @@ -0,0 +1,153 @@ +<html devsite> + <head> + <title>Functions</title> + <meta name="project_path" value="/_project.yaml" /> + <meta name="book_path" value="/_book.yaml" /> + </head> + <body> + <!-- + Copyright 2017 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. + --> + +<p>Functions in a HIDL interface are mapped to methods in the autogenerated +<code>IFoo</code> 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++.</p> + +<h2 id=parameters>Function parameters</h2> +<p>The arguments listed in the <code>.hal</code> file map to C++ data types. +Arguments that do not map to a primitive C++ type are passed by const +reference.</p> + +<p>For every HIDL function that has a return value (has a <code>generates</code> +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 <strong>one exception</strong>: If the <code>generates</code> clause +contains a single parameter that directly maps to a C++ primitive, callback +<em>elision</em> is used (the callback is removed and the return value is +returned from the function through a normal <code>return</code> statement).</p> + +<h2 id=return-values>Function return values</h2> +<p>The following functions have return values.</p> + +<h3 id=transport>Transport errors and return type</h3> +<p>The <code>generates</code> statement can result in three types of function +signatures:</p> + +<ul> +<li>For only one return value that is a C++ primitive, the +<code>generates</code> return value is returned by value from the function in a +<code>Return<T></code> object.</li> +<li>For more complicated cases, the <code>generates</code> return value(s) are +returned through the callback parameter provided with the function call itself, +and the function returns <code>Return<void></code>.</li> +<li>For when no <code>generates</code> statement exists, the function returns +<code>Return<void></code>.</li> +</ul> + +<p>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). <code>Return</code> objects store transport error +indications as well as a <code>T</code> value (except +<code>Return<void></code>).</p> + +<p>As the client-side and server-side functions have the same signature, the +server-side function must return a <code>Return</code> type even though its +implementation does not signal transport errors. <code>Return<T></code> +objects are constructed with <code>Return(myTValue)</code> (or can be implicitly +constructed from <code>mTValue</code>, such as in <code>return</code> +statements) and <code>Return<void></code> objects are constructed with +<code>Void()</code>.</p> + +<p><code>Return<T></code> objects have implicit conversion to and from +their <code>T</code> value. The <code>Return</code> object can be checked for +transport errors by calling its <code>isOk()</code> method. This check is not +required; however, if an error occurs and is not checked by the time the +<code>Return</code> object is destroyed, or a <code>T</code> value conversion is +attempted, the client process will be killed and an error logged. If +<code>isOk()</code> indicates a transport error or a call failure due to a logic +error in developer code (such as passing <code>nullptr</code> as a synchronous +callback), then <code>description()</code> 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 <code>isDeadObject()</code> is also provided. This +method indicates that <code>!isOk()</code> is because the remote object has +crashed or no longer exists. <code>isDeadObject()</code> always implies +<code>!isOk()</code>.</p> + +<h3 id=return-by>Return by value</h3> +<p>If the <code>generates</code> statement maps to a single C++ primitive, no +callback parameter is in the parameter list. Instead, an implementation provides +the return value <code>T</code> in a <code>Return<T></code> object, which +can be implicitly generated from the primitive type <code>T</code>. For +example:</p> + +<pre class="prettyprint"> +Return<uint32_t> someMethod() { + uint32_t return_data = ...; // Compute return_data + return return_data; +}; +</pre> + +<p>The method <code>Return<*>::withDefault</code> is also provided. This +method provides a value in cases where the return value is <code>!isOk()</code>. +This method also automatically marks the return object as okay so the client +process will not be killed.</p> + +<h3 id=return-callback>Return using callback parameter</h3> +<p>A callback can pass the return value of the HIDL function back to the caller. +The prototype of the callback is a <code>std::function</code> object with +parameters (taken from the <code>generates</code> statement) mapped to C++ +types. Its return value is void—the callback itself doesn't return a value.</p> + +<p>The return value of a C++ function with a callback parameter has type +<code>Return<void></code>. The server implementation is responsible only +for providing the return value. As the return values are already transferred +using the callback, the <code>T</code> template parameter is <code>void</code>: +</p> + +<pre class="prettyprint"> +Return<void> someMethod(someMethod_cb _cb); +</pre> + +<p>From their C++ implementation, server implementations should return +<code>Void()</code>, which is a static inlined function returning a +<code>Return<void></code> object. Example of a typical server method +implementation with a callback parameter:</p> + +<pre class="prettyprint"> +Return<void> someMethod(someMethod_cb _cb) { + // Do some processing, then call callback with return data + hidl_vec<uint32_t> vec = ... + _cb(vec); + return Void(); +}; +</pre> + +<h2 id=no-return>Functions without return values</h2> +<p>The C++ signature of a function without a <code>generates</code> statement +will not have a callback parameter in the parameter list. Its return type will +be <code>Return<void>.</code></p> + +<h2 id=oneway>Oneway functions</h2> +<p>Functions marked with the <code>oneway</code> keyword are asynchronous +functions (clients won't block on their execution) and do not have return +values. The C++ signature of a <code>oneway</code> function will not have a +callback parameter in the parameter list, and its C++ return value will be +<code>Return<void></code>.</p> + + </body> +</html> |