WdfRequestForwardToIoQueue function (wdfrequest.h)

[Applies to KMDF and UMDF]

The WdfRequestForwardToIoQueue method requeues an I/O request to one of the calling driver's I/O queues.

Syntax

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

Parameters

[in] Request

A handle to a framework request object.

[in] DestinationQueue

A handle to a framework queue object.

Return value

WdfRequestForwardToIoQueue returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method might return one of the following values:

This method might also return other NTSTATUS values.

A bug check occurs if the driver supplies an invalid object handle.

Remarks

The driver must own the I/O request and must have obtained the request from one of its I/O queues.

The source and destination queues cannot be the same. In other words, the driver cannot call WdfRequestForwardToIoQueue to return a request to the queue that it came from. To requeue a request to the same queue, use WdfRequestRequeue.

Both the source and destination queues must belong to the same device.

The request must not be cancelable. If the driver has called WdfRequestMarkCancelable or WdfRequestMarkCancelableEx to make the request cancelable, it must call WdfRequestUnmarkCancelable before calling WdfRequestForwardToIoQueue.

After the driver calls WdfRequestForwardToIoQueue, the driver does not own the requeued request until the framework delivers the request from the new queue to the driver. While the request is in the new queue, the framework owns the request and can cancel it without notifying the driver.

Before WdfRequestForwardToIoQueue returns, the following events can occur:

• If the destination queue was empty, the framework can deliver the requeued I/O request to one of the destination queue's request handlers.
• If the source queue's dispatching method is sequential or parallel, the framework can deliver another request to one of the source queue's request handlers.

Examples

The following code example is an EvtIoDeviceControl callback function from the PCIDRV sample driver. If a received request contains an I/O control code of IOCTL_NDISPROT_INDICATE_STATUS, the driver calls WdfRequestForwardToIoQueue to move the request to a different I/O queue.

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;
}

Requirements

See also

EvtDestroyCallback

WdfRequestMarkCancelable

WdfRequestMarkCancelableEx

WdfRequestRequeue

WdfRequestUnmarkCancelable