PTRANSFER_CODEC_VERBS 콜백 함수(hdaudio.h)

아티클
03/01/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 구조체의 Context 멤버에서 컨텍스트 값을 지정합니다.

[in] Count

codecTransfer 배열의 요소 수를 지정합니다.

[in, out] CodecTransfer

HDAUDIO_CODEC_TRANSFER 구조체의 배열에 대한 포인터입니다. 각 배열 요소는 호출자의 출력 명령과 코덱의 해당 입력 응답 모두에 대한 스토리지를 포함하는 구조체입니다.

[in] Callback

콜백 루틴에 대한 함수 포인터입니다. 이 매개 변수는 HDAUDIO_TRANSFER_COMPLETE_CALLBACK 형식의 함수 포인터입니다. 매개 변수를 NULL로 지정할 수 있습니다. 자세한 내용은 아래 설명 부분을 참조하십시오.

[in] Context

콜백 루틴에 대한 컨텍스트 값입니다. 호출자는 컨텍스트 값을 PVOID 형식으로 캐스팅합니다. 명령을 비동기적으로 완료한 후 HD Audio Bus 드라이버는 호출 매개 변수로 컨텍스트 값을 콜백 루틴에 전달합니다.

반환 값

TransferCodecVerbs는 호출이 성공하면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 루틴은 적절한 오류 코드를 반환합니다. 다음 표에는 가능한 반환 상태 코드가 표시됩니다.

반환 코드	설명
STATUS_NO_MEMORY	페이징되지 않은 메모리 부족으로 인해 요청을 명령 큐에 추가할 수 없음을 나타냅니다.

설명

이 루틴은 HD Audio Bus 드라이버에 하나 이상의 코덱 명령을 제출합니다. 버스 드라이버는 코덱에 명령을 실행하고, 명령에 대한 코덱의 응답을 검색하고, 호출자에게 응답을 출력합니다.

호출자는 HDAUDIO_CODEC_TRANSFER 구조의 배열에서 명령을 지정합니다. 각 구조체에는 명령에 대한 스토리지와 해당 명령에 대한 코덱의 응답이 모두 포함됩니다. TransferCodecVerbs를 호출하기 전에 호출자는 배열의 각 구조체에서 명령을 채웁니다. 각 명령이 완료되면 HD Audio Bus 드라이버는 코덱의 응답을 검색하고 구조체에 씁니다. 마지막 명령이 완료되면 호출자는 배열의 응답을 읽을 수 있습니다.

루틴은 동기적으로 또는 비동기적으로 작동할 수 있습니다.

호출자가 입력 매개 변수 콜백 값에 대해 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 Audio Bus 드라이버의 내부 큐에 명령을 성공적으로 추가했음을 의미합니다. 호출자는 버스 드라이버가 콜백 루틴을 호출할 때까지 해당 명령에 대한 응답을 읽으려고 시도해서는 안 됩니다.

FIFO 오버런으로 인해 응답이 유효하지 않은 경우 코덱이 명령에 응답했지만 크기가 부족한 RIRB(응답 입력 링 버퍼)로 인해 응답이 손실되었을 수 있습니다. FIFO 오버런이 잘못된 응답의 원인이 아닌 경우 코덱이 시간(시간 초과)에 응답하지 않았기 때문에 오류가 발생했을 수 있습니다. 이 경우 호출자는 명령이 코덱에 도달하지 않았다고 가정할 수 있습니다.

콜백 매개 변수가 NULL이면 호출자가 IRQL PASSIVE_LEVEL 실행 중이어야 합니다. 콜백이 NULL이 아닌 경우 호출자는 IRQL <= DISPATCH_LEVEL TransferCodecVerbs를 호출할 수 있습니다. 이 경우 호출은 코덱이 모든 명령을 처리할 때까지 기다리지 않고 즉시 반환됩니다. 명령이 완료되면 HD 오디오 버스 드라이버는 IRQL DISPATCH_LEVEL 콜백 루틴을 호출합니다.

호출자는 페이지가 지정되지 않은 풀에서 codecTransfer 배열을 할당해야 합니다.