WdfRequestChangeTarget function (wdfrequest.h)

Artikel
04/18/2022

[Applies to KMDF and UMDF]

The WdfRequestChangeTarget method verifies that a specified I/O request can be sent to a specified I/O target.

Syntax

NTSTATUS WdfRequestChangeTarget(
  [in] WDFREQUEST  Request,
  [in] WDFIOTARGET IoTarget
);

Parameters

[in] Request

A handle to a framework request object.

[in] IoTarget

A handle to a framework I/O target object.

Return value

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

Return code	Description
STATUS_INVALID_PARAMETER	An input parameter is invalid.
STATUS_INSUFFICIENT_RESOURCES	There are insufficient system resources to complete the operation.
STATUS_REQUEST_NOT_ACCEPTED	The request's array of I/O stack locations is not large enough to allow the driver to send the request to the I/O target.

This method also might return other NTSTATUS values.

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

Remarks

Your driver should call the WdfRequestChangeTarget method before it calls WdfRequestSend, if the driver sends a single I/O request to multiple I/O targets. WdfRequestChangeTarget verifies that the request can be sent to the specified I/O target.

Most drivers send each request to only one device and thus to only one I/O target. A driver either receives the request or it creates a new request by calling WdfRequestCreate.

If the driver is sending the request to one device, it calls WdfDeviceGetIoTarget to determine the device's I/O target and then calls WdfRequestSend to send the request to the target.

If the driver is sending the request to multiple devices, it calls WdfDeviceGetIoTarget for each device to determine the device's I/O target. Before calling WdfRequestSend, the driver must call WdfRequestChangeTarget to ensure that each I/O target is accessible.

For more information about WdfRequestChangeTarget, see Forwarding I/O Requests.

Examples

The following code example verifies that an I/O request can be sent to a specified device's local I/O target.

NTSTATUS  status;

status = WdfRequestChangeTarget(
                                request,
                                WdfDeviceGetIoTarget(Device)
                                );

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdfrequest.h (include Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI compliance rules	DriverCreate(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Delen via