HIDL インターフェースの関数は、自動生成された IFoo
C++ クラス宣言のメソッドにマッピングされます。各関数の名前は、C++ でも維持されます。次のセクションでは、HIDL 引数および戻り値が C++ に変換される方法について説明します。
関数のパラメータ
.hal
ファイルにリストされている引数は、C++ データ型にマッピングされます。
プリミティブ型の C++ にマッピングされない引数は、const 参照によって渡されます。
戻り値を持つ(generates
ステートメントを持つ)HIDL 関数ごとに、その関数の C++ パラメータ リストには追加の引数(HIDL 関数の戻り値で呼び出されるコールバック関数)があります。例外が 1 つあり、generates
句に C++ プリミティブへ直接マッピングする単一のパラメータが含まれる場合、コールバックの「省略」が使用されます(コールバックは削除され、戻り値は通常の return
ステートメントを介して関数から返されます)。
関数の戻り値
次の関数には戻り値があります。
トランスポート エラーと戻り値の型
generates
ステートメントは、次の 3 種類の関数シグネチャになります。
- C++ プリミティブである戻り値が 1 つだけの場合、
generates
の戻り値は、Return<T>
オブジェクトの関数から値で返されます。 - より複雑なケースの場合、
generates
の戻り値は、関数呼び出し自体で提供されるコールバック パラメータを介して返され、関数はReturn<void>
を返します。 generates
ステートメントが存在しない場合、関数はReturn<void>
を返します。
RPC 呼び出しでは、サーバーが停止した場合、トランスポート リソースが呼び出しを完了するのに不十分である場合、あるいは、渡されたパラメータにより呼び出しの完了が許可されない場合(例: 必要なコールバック関数がない)などにトランスポート エラーが発生することがあります。Return
オブジェクトは、トランスポート エラー表示と T
値(Return<void>
を除く)を格納します。
クライアント側とサーバー側の関数は同じ署名を持つため、実装がトランスポート エラーを通知しない場合もサーバー側の関数は Return
型を返します。Return<T>
オブジェクトは Return(myTValue)
で構築され(または、return
ステートメントのように mTValue
から暗黙的に構築されます)、Return<void>
オブジェクトは Void()
で構築されます。
Return<T>
オブジェクトは、T
値と暗黙的に相互変換されます。Return
オブジェクトのトランスポート エラーは、isOk()
メソッドを呼び出すことでチェックされます。このチェックは不要ですが、エラーが発生して Return
オブジェクトが破棄されるまでチェックされない場合、または T
値の変換が試行される場合、クライアント プロセスは強制終了してエラーがログに記録されます。isOk()
がデベロッパー コードの論理エラー(同期コールバックとして nullptr
を渡すなど)によるトランスポート エラーまたは呼び出しの失敗を示す場合、Return オブジェクトで description()
を呼び出してロギングに適した文字列を返すことがあります。このような場合、失敗した呼び出しの結果としてサーバーで実行されたコードの数を判断する方法はありません。また、メソッド isDeadObject()
も提供されます。このメソッドは、リモート オブジェクトがクラッシュしたか、もはや存在しないため !isOk()
であることを示します。isDeadObject()
は常に !isOk()
を意味します。
値による戻り
generates
ステートメントが単一の C++ プリミティブにマッピングされる場合、パラメータ リストにはコールバック パラメータはありません。代わりに、実装は、プリミティブ型 T
から暗黙的に生成される Return<T>
オブジェクトに戻り値 T
を提供します。次に例を示します。
Return<uint32_t> someMethod() { uint32_t return_data = ...; // Compute return_data return return_data; };
また、メソッド Return<*>::withDefault
も提供されます。このメソッドは、戻り値が !isOk()
の場合に値を提供します。また、このメソッドは、クライアント プロセスが強制終了されないように、戻りオブジェクトを自動的に OK としてマークします。
コールバック パラメータを使用した戻り
コールバックは、HIDL 関数の戻り値を呼び出し元に渡します。
コールバックのプロトタイプは、C++ 型にマッピングされたパラメータ(generates
ステートメントから取得)を持つ std::function
オブジェクトです。この戻り値は void で、コールバック自体は値を返しません。
コールバック パラメータを持つ C++ 関数の戻り値の型は Return<void>
です。サーバーの実装は、戻り値の提供のみを行います。戻り値はすでにコールバックを使用して転送されているため、T
テンプレートのパラメータは次のように void
となります。
Return<void> someMethod(someMethod_cb _cb);
C++ の実装から、サーバーの実装は Void()
(Return<void>
オブジェクトを返す静的なインライン関数)を返します。コールバック パラメータを使用した典型的なサーバー メソッドの実装の例を次に示します。
Return<void> someMethod(someMethod_cb _cb) { // Do some processing, then call callback with return data hidl_vec<uint32_t> vec = ... _cb(vec); return Void(); };
戻り値を持たない関数
generates
ステートメントのない関数の C++ 署名は、パラメータ リストにコールバック パラメータを持ちません。この戻り値の型は Return<void>.
になります。
一方向性関数
oneway
というキーワードでマークされた関数は非同期関数で(クライアントは実行をブロックしません)、戻り値を持ちません。oneway
関数の C++ シグネチャはパラメータ リストにコールバック パラメータを持たず、C++ 戻り値は Return<void>
となります。