PFNKSHANDLER 콜백 함수(ks.h)

아티클
08/07/2023

미니 드라이버 제공 루틴은 커널 스트리밍이 IOCTL_KS_METHOD get/set 속성 요청을 받을 때 호출됩니다. 관련 KSMETHOD_ITEM KSPROPERTY_ITEM구조에서 이 처리기에 대한 포인터를 제공합니다.

구문

PFNKSHANDLER Pfnkshandler;

NTSTATUS Pfnkshandler(
  [in]      PIRP Irp,
  [in]      PKSIDENTIFIER Request,
  [in, out] PVOID Data
)
{...}

매개 변수

[in] Irp

메서드 또는 속성 요청을 포함하는 IRP를 지정합니다.

[in] Request

메서드 매개 변수의 정렬된 복사본을 지정합니다. 일반적으로 KSMETHOD 또는 KSPROPERTY 구조체에 대한 포인터입니다.

[in, out] Data

메서드의 KSMETHOD_ITEM 구조에 지정된 플래그에 따라 원래 데이터 매개 변수의 시스템 주소 또는 메서드 데이터 매개 변수의 정렬된 복사본을 지정합니다.

반환 값

메서드가 처리되고 데이터 버퍼가 KSMETHOD_ITEM 지정된 플래그에 따라 채워진 경우 STATUS_SUCCESS 반환합니다. 데이터를 반환하는 경우 드라이버는 Irp-IoStatus.Information 필드를 설정해야 하지만 Irp-IoStatus.Status>> 필드를 설정하거나 IRP를 완료해서는 안 됩니다. IRP가 비동기적으로 완료될 경우 보류 중인 IRP를 표시합니다.

또는 메서드가 처리되었지만 특정 요청이 완료되지 않았으며 호출 도우미 함수에서 완료해야 하는 경우 STATUS_SOME_NOT_MAPPED 반환합니다. 메서드가 지원되지 않거나 매개 변수 오류가 발생했음을 나타내는 다른 오류 메시지를 반환합니다.

설명

미니 드라이버는 KSMETHOD_ITEM 구조체의 MethodHandler 멤버에서 이 루틴의 주소를 지정합니다.

KStrMethodHandler 및 KStrSupportHandler에 사용되는 처리기 선언은 동일한 매개 변수와 반환 값을 사용하여 속성 및 이벤트 집합의 처리기에도 사용됩니다.

KsMethodHandler와 같은 도우미 함수가 데이터 버퍼가 쓰기 또는 수정 버퍼로 정의된 메서드 처리기를 호출하는 경우 메서드 처리기는 IRP(Irp 매개 변수) 내의 IoStatus 멤버에 대한 IO_STATUS_BLOCK 구조의 정보 멤버를 해당 데이터 버퍼의 크기로 설정해야 합니다. 미니 드라이버는 메서드에 대한 KSMETHOD_ITEM 구조의 Flags 멤버를 KSMETHOD_TYPE_WRITE 또는 KSMETHOD_TYPE_MODIFY 설정하여 메서드 처리기의 데이터 버퍼를 각각 쓰기 또는 수정으로 정의합니다.

다음 코드 조각은 IRP에서 반환되는 데이터 버퍼의 크기를 설정하는 메서드 처리기의 구현 예제를 보여줍니다.

NTSTATUS
  MethodHandler(PIRP pIrp, PKSIDENTIFIER Request, PVOID Data) {
    NTSTATUS Status = STATUS_UNSUCCESSFUL;
    // Pointer to hold the position on the Irp stack
    PIO_STACK_LOCATION  pIrpStack  = NULL;
    ASSERT(pIrp);
    if(Data) {
        // Modify data here
    }
    // Find the current Irp stack.
    pIrpStack = IoGetCurrentIrpStackLocation(pIrp);
    if(pIrpStack) {
        // Set the size of the returning Irp data.
        pIrp->IoStatus.Information =
          pIrpStack->Parameters.DeviceIoControl.OutputBufferLength;
        Status = STATUS_SUCCESS;
    }
    return(Status);
}

미니 드라이버는 KSPROPERTY_ITEM 구조체의 GetPropertyHandler 멤버에서 이 루틴의 주소를 지정합니다.

미니 드라이버는 KSPROPERTY_ITEM 구조체의 SetPropertyHandler 멤버에서 이 루틴의 주소를 지정합니다.

미니 드라이버는 KSMETHOD_ITEM 구조체의 SupportHandler 멤버에서 이 루틴의 주소를 지정합니다.

KStrMethodHandler 및 KStrSupportHandler에 사용되는 처리기 선언은 동일한 매개 변수와 반환 값을 사용하여 속성 및 이벤트 집합의 처리기에도 사용됩니다.