PTRANSFER_CODEC_VERBS コールバック関数 (hdaudio.h)

[アーティクル]
07/25/2023

TransferCodecVerbs ルーチンは、1 つ以上のコマンドをコーデックまたはコーデックに転送し、それらのコマンドへの応答を取得します。

TransferCodecVerbs ルーチンの関数ポインター型は、次のように定義されます。

構文

PTRANSFER_CODEC_VERBS PtransferCodecVerbs;

NTSTATUS PtransferCodecVerbs(
  [in]      PVOID _context,
  [in]      ULONG Count,
  [in, out] PHDAUDIO_CODEC_TRANSFER CodecTransfer,
  [in]      PHDAUDIO_TRANSFER_COMPLETE_CALLBACK Callback,
  [in]      PVOID Context
)
{...}

パラメーター

[in] _context

HDAUDIO_BUS_INTERFACE、HDAUDIO_BUS_INTERFACE_V2、または HDAUDIO_BUS_INTERFACE_BDL 構造体の Context メンバーのコンテキスト値を指定します。

[in] Count

codecTransfer 配列内の要素の数を指定します。

[in, out] CodecTransfer

HDAUDIO_CODEC_TRANSFER構造体の配列へのポインター。各配列要素は、呼び出し元からの出力コマンドとコーデックからの対応する入力応答の両方のストレージを含む構造体です。

[in] Callback

コールバックルーチンへの関数ポインター。このパラメーターは、HDAUDIO_TRANSFER_COMPLETE_CALLBACK型の関数ポインターです。パラメーターは NULL として指定できます。詳細については、「解説」を参照してください。

[in] Context

コールバックルーチンのコンテキスト値。呼び出し元は、コンテキスト値を PVOID 型にキャストします。コマンドを非同期的に完了すると、HD Audio バスドライバーはコンテキスト値を呼び出しパラメーターとしてコールバックルーチンに渡します。

戻り値

TransferCodecVerbs は、呼び出しが成功した場合にSTATUS_SUCCESSを返します。それ以外の場合、ルーチンは適切なエラーコードを返します。次の表は、可能な戻り状態コードを示しています。

リターンコード	説明
STATUS_NO_MEMORY	非ページメモリが不足しているため、コマンドキューに要求を追加できなかったことを示します。

注釈

このルーチンは、HD オーディオバスドライバーに 1 つ以上のコーデックコマンドを送信します。バスドライバーは、コーデックにコマンドを発行し、コマンドに対するコーデックの応答を取得し、呼び出し元に応答を出力します。

呼び出し元は、HDAUDIO_CODEC_TRANSFER構造体の配列内のコマンドを指定します。各構造体には、コマンドとそのコマンドに対するコーデックの応答の両方のストレージが含まれています。 TransferCodecVerbs を呼び出す前に、呼び出し元は配列内の各構造体のコマンドを入力します。各コマンドが完了すると、HD Audio バスドライバーはコーデックの応答を取得し、それを構造体に書き込みます。最後のコマンドが完了すると、呼び出し元は配列から応答を読み取ることができます。

ルーチンは、同期的または非同期的に動作できます。

呼び出し元が入力パラメーター コールバックの値に NULL を指定した場合、HD Audio バスドライバーは codecTransfer 配列のコマンドを同期的に完了します。 (つまり、コーデックによってすべてのコマンドが処理され、それらのコマンドに対する応答が使用可能になった後にのみ、ルーチンが返されます)。
呼び出し元がコールバック パラメーターに NULL 以外の値を指定した場合、ルーチンは非同期的に動作します。 (つまり、ルーチンは、コーデックがすべてのコマンドを処理するのを待たずに、コマンドを内部キューに追加した直後にを返します。コーデックがコマンドを処理した後、HD Audio バスドライバーはコールバックルーチンを呼び出します。非同期の場合、呼び出し元は、バスドライバーがコールバックルーチンを呼び出す前に、コマンドへの応答を読み取ろうとしないでください。

コールバックパラメーターの関数ポインター型は、次のように定義されます。

typedef VOID
  (*PHDAUDIO_TRANSFER_COMPLETE_CALLBACK)
    (HDAUDIO_CODEC_TRANSFER *, PVOID);

最初の呼び出しパラメーターは、codec コマンドとコールバックをトリガーした応答を含む codecTransfer 配列要素へのポインターです。 2 番目の呼び出しパラメーターは、 TransferCodecVerbs ルーチンの callbackContext パラメーターで以前に指定されたものと同じコンテキスト値です。

成功した場合、 TransferCodecVerbs は STATUS_SUCCESSを返します。この状態コードの意味は、ルーチンが同期的に動作するか非同期的に動作するかによって異なります。

同期ケース (コールバック が NULL) の場合、STATUS_SUCCESSは、バスドライバーが codecTransfer 配列内のすべてのコマンドをコーデックに持ち、ルーチンがそれらのコマンドに対するすべての応答を配列に書き込んだことを意味します。ただし、呼び出し元は、個々の応答をチェックして、それらが有効かどうかを判断する必要があります。コーデックのタイムアウトまたは FIFO オーバーランが原因で、個々の応答が無効である可能性があります。
非同期の場合 (コールバック は NULL 以外)、STATUS_SUCCESSは、ルーチンが HD Audio バスドライバーの内部キューにコマンドを正常に追加したことを意味します。呼び出し元は、バスドライバーがコールバックルーチンを呼び出すまで、これらのコマンドへの応答を読み取ろうとしないでください。

FIFO オーバーランが原因で応答が無効な場合は、コーデックがコマンドに応答したが、十分なサイズの応答入力リングバッファー (RIRB) が原因で応答が失われた可能性があります。 FIFO オーバーランが無効な応答の原因ではない場合は、コーデックが時間内に応答しなかった (タイムアウト) ため、エラーが発生した可能性があります。この場合、呼び出し元はコマンドがコーデックに到達しなかったと想定できます。

コールバック パラメーターが NULL の場合、呼び出し元は IRQL PASSIVE_LEVELで実行されている必要があります。 コールバックが NULL 以外の場合、呼び出し元は IRQL <= DISPATCH_LEVEL で TransferCodecVerbs を呼び出すことができます。その場合、呼び出しはコーデックがすべてのコマンドを処理するのを待たずに直ちに返されます。コマンドが完了すると、HD Audio バスドライバーは IRQL DISPATCH_LEVELでコールバックルーチンを呼び出します。

呼び出し元は、非ページプールから codecTransfer 配列を割り当てる必要があります。