WdfRequestRetrieveOutputBuffer 함수(wdfrequest.h)

  • 아티클

[KMDF 및 UMDF에 적용]

WdfRequestRetrieveOutputBuffer 메서드는 I/O 요청의 출력 버퍼를 검색합니다.

구문

NTSTATUS WdfRequestRetrieveOutputBuffer(
  [in]            WDFREQUEST Request,
  [in]            size_t     MinimumRequiredSize,
  [out]           PVOID      *Buffer,
  [out, optional] size_t     *Length
);

매개 변수

[in] Request

프레임워크 요청 개체에 대한 핸들입니다.

[in] MinimumRequiredSize

드라이버가 I/O 요청을 처리하는 데 필요한 최소 버퍼 크기(바이트)입니다.

[out] Buffer

버퍼의 주소를 받는 위치에 대한 포인터입니다.

[out, optional] Length

버퍼의 크기를 받는 위치에 대한 포인터(바이트)입니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다.

반환 값

WdfRequestRetrieveOutputBuffer는 작업이 성공하면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 이 메서드는 다음 값 중 하나를 반환할 수 있습니다.

반환 코드 설명
STATUS_INVALID_PARAMETER
 입력 매개 변수가 잘못되었습니다.
STATUS_BUFFER_TOO_SMALL
 출력 버퍼의 길이가 0이거나 MinimumRequiredSize 매개 변수가 버퍼의 실제 크기보다 큰 버퍼 크기를 지정합니다.
STATUS_INVALID_DEVICE_REQUEST
 요청 유형이 잘못되었거나 요청이 버퍼링되거나 직접 I/O를 사용하지 않습니다. 데이터 버퍼에 액세스하기 위해 지원되는 방법에 대한 자세한 내용은 다음 설명 섹션을 참조하세요.
STATUS_INTERNAL_ERROR
 요청이 이미 완료되었습니다.
STATUS_INSUFFICIENT_RESOURCES
 메모리가 부족합니다.
 

이 메서드는 다른 NTSTATUS 값을 반환할 수도 있습니다.

드라이버가 잘못된 개체 핸들을 제공하는 경우 버그 검사 발생합니다.

설명

요청의 출력 버퍼는 드라이버가 요청의 발신자에게 제공하는 디스크의 데이터와 같은 정보를 받습니다. 드라이버는 WdfRequestRetrieveOutputBuffer 를 호출하여 읽기 요청 또는 디바이스 I/O 제어 요청에 대한 출력 버퍼를 가져올 수 있지만 쓰기 요청은 출력 데이터를 제공하지 않기 때문에 쓰기 요청에 대해서는 가져올 수 없습니다.

WdfRequestRetrieveOutputBuffer 메서드는 버퍼링된 I/O 메서드 또는 직접 I/O 메서드를 사용하여 데이터 버퍼에 액세스하는 I/O 요청에 대한 출력 버퍼를 검색합니다. 요청의 I/O 제어 코드가 IRP_MJ_INTERNAL_DEVICE_CONTROL 경우 또는 요청이 다른 커널 모드 드라이버에서 온 경우 WdfRequestRetrieveOutputBuffer 는 버퍼링되거나 직접 I/O를 사용하지 않는 I/O 요청도 지원합니다.

WdfRequestRetrieveOutputBuffer가 STATUS_SUCCESS 반환하는 경우 드라이버는 주소와 선택적으로 출력 버퍼의 크기를 받습니다.

드라이버는 Request 매개 변수가 나타내는 I/O 요청을 완료할 때까지 검색된 버퍼에 액세스할 수 있습니다.

드라이버는 WdfRequestRetrieveOutputBuffer를 호출하는 대신 버퍼를 나타내는 프레임워크 메모리 개체를 만드는 WdfRequestRetrieveOutputMemory를 호출할 수 있습니다.

WdfRequestRetrieveOutputBuffer에 대한 자세한 내용은 Framework-Based 드라이버에서 데이터 버퍼 액세스를 참조하세요.

예제

다음 코드 예제는 EvtIoDeviceControl 콜백 함수의 일부입니다. 이 예제에서는 USB 디바이스의 구성 설명자를 가져오고 설명자를 I/O 요청의 출력 버퍼에 배치합니다.

VOID
MyEvtIoDeviceControl(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  OutputBufferLength,
    IN size_t  InputBufferLength,
    IN ULONG  IoControlCode    
    )
{
    WDFDEVICE  device;
    PDEVICE_CONTEXT  pDevContext;
    size_t  bytesReturned = 0;
    NTSTATUS  status;

    device = WdfIoQueueGetDevice(Queue);
    //
    // GetDeviceContext is a driver-defined function 
    // to retrieve device object context space.
    //
    pDevContext = GetDeviceContext(device);

    switch(IoControlCode) {

      case IOCTL_OSRUSBFX2_GET_CONFIG_DESCRIPTOR: {
 
        PUSB_CONFIGURATION_DESCRIPTOR  configurationDescriptor = NULL;
        USHORT  requiredSize;

        //
        // First, get the size of the USB configuration descriptor.
        //
        status = WdfUsbTargetDeviceRetrieveConfigDescriptor(
                                                pDevContext->UsbDevice,
                                                NULL,
                                                &requiredSize
                                                );
        if (status == STATUS_BUFFER_TOO_SMALL) {
            break;
        }

        //
        // Get the buffer. Make sure the buffer is big
        // enough to hold the configuration descriptor.
        //
        status = WdfRequestRetrieveOutputBuffer(
                                                Request, 
                                                (size_t)requiredSize,
                                                &configurationDescriptor,
                                                NULL
                                                );
        if(!NT_SUCCESS(status)){
            break;
        }
        //
        // Now get the config descriptor.
        //
        status = WdfUsbTargetDeviceRetrieveConfigDescriptor(
                                                pDevContext->UsbDevice,
                                                configurationDescriptor,
                                                &requiredSize
                                                );
        if (!NT_SUCCESS(status)) {
            break;
        }

        bytesReturned = requiredSize;
      }
        break;
...
    (Other case statements removed.)
...
    default:
        status = STATUS_INVALID_DEVICE_REQUEST;
        break;
    }
    //
    // Complete the request.
    //
    WdfRequestCompleteWithInformation(
                                      Request,
                                      status,
                                      bytesReturned
                                      );
    return;
}

요구 사항

요구 사항 값
대상 플랫폼 유니버설
최소 KMDF 버전 1.0
최소 UMDF 버전 2.0
머리글 wdfrequest.h(Wdf.h 포함)
라이브러리 Wdf01000.sys(KMDF); WUDFx02000.dll(UMDF)
IRQL <=DISPATCH_LEVEL
DDI 규정 준수 규칙 BufAfterReqCompletedIntIoctl(kmdf), BufAfterReqCompletedIntIoctlA(kmdf), BufAfterReqCompletedIoctl(kmdf), BufAfterReqCompletedIoctlA(kmdf), BufAfterReqCompletedRead(kmdf), BufAfterReqCompletedReadA(kmdf), BufAfterReqCompletedWrite(kmdf), DriverCreate(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), OutputBufferAPI(kmdf)

추가 정보

WdfRequestRetrieveInputBuffer

WdfRequestRetrieveOutputMemory