PTRANSFER_CODEC_VERBS hdaudio.h (回呼函式)

發行項
02/26/2024

TransferCodecVerbs 例程會將一或多個命令傳送至編解碼器或編解碼器，並擷取這些命令的回應。

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 結構的內容成員指定內容值。

[in] Count

指定 codecTransfer 陣列中的項目數目。

[in, out] CodecTransfer

HDAUDIO_CODEC_TRANSFER 結構的陣列指標。每個數位元素都是一個結構，其中包含來自呼叫端的輸出命令以及來自編解碼器之對應輸入響應的記憶體。

[in] Callback

回呼例程的函式指標。此參數是類型為 HDAUDIO_TRANSFER_COMPLETE_CALLBACK 的函式指標。參數可以指定為 NULL。如需詳細資訊，請參閱接下來的＜備註＞一節。

[in] Context

回呼例程的內容值。呼叫端會將內容值轉換成 PVOID 類型。以異步方式完成命令之後，HD 音訊總線驅動程式會將內容值傳遞至回呼例程作為呼叫參數。

傳回值

如果呼叫成功，TransferCodecVerbs 會傳回STATUS_SUCCESS。否則，例程會傳回適當的錯誤碼。下表顯示可能的傳回狀態代碼。

傳回碼	Description
STATUS_NO_MEMORY	表示因為記憶體不足而無法將要求新增至命令佇列。

備註

此例程會將一或多個編解碼器命令提交至 HD 音訊總線驅動程式。總線驅動程式會將命令發出給編解碼器、擷取編解碼器對命令的回應，並將響應輸出給呼叫端。

呼叫端會指定HDAUDIO_CODEC_TRANSFER結構陣列中的命令。每個結構都包含命令的記憶體，以及編解碼器對該命令的回應。呼叫 TransferCodecVerbs 之前，呼叫端會在陣列中的每個結構中填入命令。當每個命令完成時，HD 音訊總線驅動程式會擷取編解碼器的回應，並將它寫入結構。最後一個命令完成之後，呼叫端可以從陣列讀取回應。

例程可以同步或異步操作：

如果呼叫端針對輸入參數回呼的值指定 NULL，HD 音訊總線驅動程式會同步完成 codecTransfer 陣列中的命令。 (換句話說，例程只會在編解碼器處理所有命令和這些命令的回應可供使用之後傳回。)
如果呼叫端指定回呼參數的非 NULL 值，則例程會以異步方式運作。 (換句話說，例程會在將命令新增至其內部佇列之後立即傳回，而不等待編解碼器處理所有命令。) 在編解碼器處理命令之後，HD 音頻總線驅動程式會呼叫回呼例程。在異步的情況下，呼叫端不應該在總線驅動程式呼叫回呼例程之前，嘗試讀取命令的回應。

回呼參數的函式指標類型定義為：

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

第一個呼叫參數是 codecTransfer 數位專案的指標，其中包含編解碼器命令和觸發回呼的回應。第二個呼叫參數是先前在 TransferCodecVerbs 例程的 callbackContext 參數中指定的相同內容值。

如果成功， TransferCodecVerbs 會傳回STATUS_SUCCESS。此狀態代碼的意義取決於例程是否以同步或異步方式運作：

在同步案例 (中，回呼為NULL) ，STATUS_SUCCESS表示總線驅動程式會將 codecTransfer 陣列中的所有命令寫入編解碼器，而且例程已將所有回應寫入數位中。不過，呼叫端必須檢查個別回應，以判斷它們是否有效。個別回應可能會因為編解碼器逾時或 FIFO 溢出而無效。
在異步情況下， (回呼為非 NULL) ，STATUS_SUCCESS表示例程已成功將命令新增至 HD 音頻總線驅動程式的內部佇列。在總線驅動程式呼叫回呼例程之前，呼叫端不得嘗試讀取這些命令的回應。

如果因 FIFO 溢出而造成回應無效，可能是因為編解碼器回應命令，但回應因為回應大小不足而遺失， (RIRB) 。如果 FIFO 過度執行不是無效回應的原因，可能會發生失敗，因為編解碼器未及時回應， (逾時) 。在此情況下，呼叫端可以假設命令未連線到編解碼器。

如果回呼參數為 NULL，呼叫端必須在 IRQL PASSIVE_LEVEL執行。如果回呼為非 NULL，呼叫端可以在 IRQL <= DISPATCH_LEVEL呼叫 TransferCodecVerbs，在此情況下，呼叫會立即傳回，而不需要等候編解碼器處理所有命令;在命令完成之後，HD 音訊總線驅動程式會在 IRQL DISPATCH_LEVEL呼叫回呼例程。

呼叫端必須從非分頁集區配置 codecTransfer 陣列。