関数

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> となります。