WdfRequestForwardToParentDeviceIoQueue function (wdfrequest.h)

[Applies to KMDF only]

The WdfRequestForwardToParentDeviceIoQueue method requeues an I/O request from a child device's I/O queue to a specified I/O queue of the child's parent device.

Syntax

NTSTATUS WdfRequestForwardToParentDeviceIoQueue(
  [in] WDFREQUEST                   Request,
  [in] WDFQUEUE                     ParentDeviceQueue,
  [in] PWDF_REQUEST_FORWARD_OPTIONS ForwardOptions
);

Parameters

[in] Request

A handle to a framework request object.

[in] ParentDeviceQueue

A handle to a framework queue object.

[in] ForwardOptions

A pointer to a caller-allocated WDF_REQUEST_FORWARD_OPTIONS structure.

Return value

WdfRequestForwardToParentDeviceIoQueue 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

Before a driver can call WdfRequestForwardToParentDeviceIoQueue, it must call WdfPdoInitAllowForwardingRequestToParent.

The driver must use the same method to access data buffers (buffered, direct, or neither) for both the parent device and the child device.

If your driver will call WdfRequestForwardToParentDeviceIoQueue to requeue an I/O request, the driver must not use the request object as the parent of other framework objects, such as timer objects or work item objects.

If your driver has called WdfDeviceInitSetRequestAttributes to specify context space for the parent device's request objects, the framework does not add this context space to request objects that the driver receives in a child device's queue. The driver can call WdfObjectAllocateContext to add the context space to a request object before the driver calls WdfRequestForwardToParentDeviceIoQueue. On the other hand, if the driver called WdfDeviceInitSetRequestAttributes for the child device's request objects, and if the parent device's request objects use context space that is equal to or smaller than the child device's context space, the driver can use the request object's context space without calling WdfObjectAllocateContext.

Currently, the driver must use the send and forget option for all requeued I/O requests. Therefore, be aware that by the time that the framework deletes a requeued request object, it might have already removed the child device that originally received the request object. Thus, the driver must not use the EvtCleanupCallback or EvtDestroyCallback function of a requeued request object to access child device resources, because the resources might be removed before the EvtCleanupCallback or EvtDestroyCallback function runs.

For more information about WdfRequestForwardToParentDeviceIoQueue, see Requeuing I/O Requests.

Examples

The following code example first determines the parent device of a device that received an I/O request, and then it requeues the I/O request to the parent device's default I/O queue.

WDFDEVICE device, parentDevice;
WDF_REQUEST_FORWARD_OPTIONS forwardOptions;
NTSTATUS status;

device = WdfIoQueueGetDevice(WdfRequestGetIoQueue(Request));
parentDevice = WdfPdoGetParent(device);

WDF_REQUEST_FORWARD_OPTIONS_INIT(&forwardOptions);
status = WdfRequestForwardToParentDeviceIoQueue(
             Request,
             WdfDeviceGetDefaultQueue(parentDevice),
             &forwardOptions
             );
if (!NT_SUCCESS(status)) {
    WdfRequestComplete(
                       Request,
                       status
                       );
  }

Requirements

See also

WdfPdoInitAllowForwardingRequestToParent