WdfRequestWdmFormatUsingStackLocation function (wdfrequest.h)

Article
02/22/2024

[Applies to KMDF only]

The WdfRequestWdmFormatUsingStackLocation method formats an I/O request by copying the contents of a specified WDM I/O stack location structure to the next stack location in the request.

Syntax

void WdfRequestWdmFormatUsingStackLocation(
  [in] WDFREQUEST         Request,
  [in] PIO_STACK_LOCATION Stack
);

Parameters

[in] Request

A handle to a framework request object.

[in] Stack

A pointer to an IO_STACK_LOCATION structure that contains driver-supplied information.

Return value

None

Remarks

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

The WdfRequestWdmFormatUsingStackLocation method copies the information that is supplied by the Stack parameter into the next IRP stack location in the request.

WdfRequestWdmFormatUsingStackLocation formats the request independent of whether the I/O target object of the request is local or remote.

If you want to set a completion routine for the request, your driver must call WdfRequestSetCompletionRoutine after calling WdfRequestWdmFormatUsingStackLocation.

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

Examples

The following code example supplies an IO_STACK_LOCATION structure for an I/O request, sets a CompletionRoutine callback function, and then sends the request to an I/O target.

IO_STACK_LOCATION  ioStackLocation;
BOOLEAN sendStatus;
...
//
// Initialize the IO_STACK_LOCATION structure here.
//
...
//
// Assign the IO_STACK_LOCATION structure to the request.
//
WdfRequestWdmFormatUsingStackLocation(
                                      request,
                                      &ioStackLocation
                                      );
//
// Assign a CompletionRoutine callback function.
//
WdfRequestSetCompletionRoutine(
                               Request,
                               RequestTimeoutComplete,
                               NULL
                               );
//
// Send the request.
//
sendStatus = WdfRequestSend(
                            Request,
                            target,
                            NULL
                            );

The following code example illustrates how to send a PnP IRP_MN_QUERY_CAPABILITIES IRP to an IO target.

target = WdfDeviceGetIoTarget(Device);
status = WdfRequestCreate(WDF_NO_OBJECT_ATTRIBUTES,
                          target,
                          &request);

if (!NT_SUCCESS(status)) {
    // Log failure and leave
}

//
// PnP IRPs must be initialized with STATUS_NOT_SUPPORTED
//
WDF_REQUEST_REUSE_PARAMS_INIT(&reuse,
                              WDF_REQUEST_REUSE_NO_FLAGS,
                              STATUS_NOT_SUPPORTED);

WdfRequestReuse(request, &reuse);


//
// Initialize device capabilities
//
RtlZeroMemory(Capabilities, sizeof(DEVICE_CAPABILITIES));
Capabilities->Size = sizeof(DEVICE_CAPABILITIES);
Capabilities->Version  =  1;
Capabilities->Address  = (ULONG) -1;
Capabilities->UINumber = (ULONG) -1;
RtlZeroMemory(&stack, sizeof(stack));
stack.MajorFunction = IRP_MJ_PNP;
stack.MinorFunction = IRP_MN_QUERY_CAPABILITIES;
stack.Parameters.DeviceCapabilities.Capabilities = Capabilities;

WdfRequestWdmFormatUsingStackLocation(request, &stack);

WDF_REQUEST_SEND_OPTIONS_INIT(&options,
                              WDF_REQUEST_SEND_OPTION_SYNCHRONOUS);

if (WdfRequestSend(request, target, &options) == FALSE) {
    // Log failure
}

status = WdfRequestGetStatus(request);

if (!NT_SUCCESS(status)) {
    // Log failure
}

// Remember to delete the WDFREQUEST after creating it
if (request != NULL) {
    WdfObjectDelete(request);
}

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Header	wdfrequest.h (include Wdf.h)
Library	Wdf01000.sys (see Framework Library Versioning.)
IRQL	<=DISPATCH_LEVEL
DDI compliance rules	DriverCreate(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf)

Share via