WdfRequestForwardToIoQueue 함수(wdfrequest.h)

아티클
08/08/2023

[KMDF 및 UMDF에 적용]

WdfRequestForwardToIoQueue 메서드는 호출 드라이버의 I/O 큐 중 하나에 I/O 요청을 다시 큐에 추가합니다.

구문

NTSTATUS WdfRequestForwardToIoQueue(
  [in] WDFREQUEST Request,
  [in] WDFQUEUE   DestinationQueue
);

매개 변수

[in] Request

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

[in] DestinationQueue

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

반환 값

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

반환 코드	설명
STATUS_INVALID_DEVICE_REQUEST	다음 중 하나가 발생하면 이 값이 반환됩니다. 드라이버가 I/O 큐에서 요청을 가져오지 못했습니다. 원본 큐와 대상 큐는 동일합니다. 원본 및 대상 큐는 동일한 디바이스에 속하지 않습니다. 드라이버가 요청을 소유하지 않습니다. 요청을 취소할 수 있습니다.
STATUS_WDF_BUSY	대상 큐가 새 요청을 수락하지 않습니다.

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

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

설명

드라이버는 I/O 요청을 소유 해야 하며 해당 I/O 큐 중 하나에서 요청을 가져와야 합니다.

원본 큐와 대상 큐는 동일할 수 없습니다. 즉, 드라이버는 WdfRequestForwardToIoQueue 를 호출하여 수신된 큐에 요청을 반환할 수 없습니다. 요청을 동일한 큐에 다시 큐에 추가하려면 WdfRequestRequeue를 사용합니다.

원본 큐와 대상 큐는 모두 동일한 디바이스에 속해야 합니다.

요청을 취소할 수 없습니다. 드라이버가 요청을 취소할 수 있도록 WdfRequestMarkCancelable 또는 WdfRequestMarkCancelableEx를 호출한 경우 WdfRequestForwardToIoQueue를 호출하기 전에 WdfRequestUnmarkCancelable을 호출해야 합니다.

드라이버가 WdfRequestForwardToIoQueue를 호출한 후 프레임워크가 새 큐에서 드라이버로 요청을 전달할 때까지 드라이버는 다시 큐에 넣은 요청을 소유하지 않습니다. 요청이 새 큐에 있는 동안 프레임워크는 요청을 소유하고 드라이버에 알리지 않고 취소할 수 있습니다.

WdfRequestForwardToIoQueue가 반환되기 전에 다음 이벤트가 발생할 수 있습니다.

대상 큐가 비어 있는 경우 프레임워크는 다시 큐에 넣은 I/O 요청을 대상 큐의 요청 처리기 중 하나에 전달할 수 있습니다.
원본 큐의 디스패치 메서드 가 순차적이거나 병렬인 경우 프레임워크는 원본 큐의 요청 처리기 중 하나에 다른 요청을 전달할 수 있습니다.

WdfRequestForwardToIoQueue에 대한 자세한 내용은 I/O 요청 다시 큐 및 I/O 큐 관리를 참조하세요.

예제

다음 코드 예제는 PCIDRV 샘플 드라이버의 EvtIoDeviceControl 콜백 함수입니다. 수신된 요청에 IOCTL_NDISPROT_INDICATE_STATUS I/O 제어 코드가 포함된 경우 드라이버는 WdfRequestForwardToIoQueue 를 호출하여 요청을 다른 I/O 큐로 이동합니다.

VOID
PciDrvEvtIoDeviceControl(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  OutputBufferLength,
    IN size_t  InputBufferLength,
    IN ULONG  IoControlCode
    )
{
    NTSTATUS  status= STATUS_SUCCESS;
    PFDO_DATA  fdoData = NULL;
    WDFDEVICE  hDevice;
    WDF_REQUEST_PARAMETERS  params;

    UNREFERENCED_PARAMETER(OutputBufferLength);
    UNREFERENCED_PARAMETER(InputBufferLength);

    hDevice = WdfIoQueueGetDevice(Queue);
    fdoData = FdoGetData(hDevice);

    WDF_REQUEST_PARAMETERS_INIT(&params);
    WdfRequestGetParameters(
                            Request,
                            &params
                            );

    switch (IoControlCode)
    {
        case IOCTL_NDISPROT_QUERY_OID_VALUE:
            NICHandleQueryOidRequest(
                                     Queue,
                                     Request,
                                     &params
                                     );
            break;

        case IOCTL_NDISPROT_SET_OID_VALUE:
            NICHandleSetOidRequest(
                                   Queue,
                                   Request,
                                   &params
                                   );
            break;

        case IOCTL_NDISPROT_INDICATE_STATUS:
            status = WdfRequestForwardToIoQueue(
                                                Request,
                                                fdoData->PendingIoctlQueue
                                                );
            if(!NT_SUCCESS(status)){
                WdfRequestComplete(
                                   Request,
                                   status
                                   );
                break;
            }
            break;

        default:
            WdfRequestComplete(
                               Request,
                               STATUS_INVALID_DEVICE_REQUEST
                               );
            break;
    }
    return;
}

요구 사항

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