WdfUsbTargetPipeFormatRequestForReset function (wdfusb.h)

Article
04/18/2022

[Applies to KMDF and UMDF]

The WdfUsbTargetPipeFormatRequestForReset method builds a reset request for a specified USB pipe, but it does not send the request.

Syntax

NTSTATUS WdfUsbTargetPipeFormatRequestForReset(
  [in] WDFUSBPIPE Pipe,
  [in] WDFREQUEST Request
);

Parameters

[in] Pipe

A handle to a framework pipe object that was obtained by calling WdfUsbInterfaceGetConfiguredPipe.

[in] Request

A handle to a framework request object. For more information, see the following Remarks section.

Return value

WdfUsbTargetPipeFormatRequestForReset returns the USB I/O target's completion status value if the operation succeeds. Otherwise, this method can return one of the following values:

Return code	Description
STATUS_INVALID_PARAMETER	An invalid parameter was detected.
STATUS_INSUFFICIENT_RESOURCES	Insufficient memory was available.
STATUS_REQUEST_NOT_ACCEPTED	The I/O request packet (IRP) that the Request parameter represents does not provide enough IO_STACK_LOCATION structures to allow the driver to forward the request.

This method also might return other NTSTATUS values.

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

Remarks

Use WdfUsbTargetPipeFormatRequestForReset, followed by WdfRequestSend, to send a USB reset request either synchronously or asynchronously. Alternatively, use the WdfUsbTargetPipeResetSynchronously method to send a request synchronously.

Before the driver calls WdfRequestSend, it must call WdfIoTargetStop and it must complete or cancel all I/O requests that it has sent to the I/O target. The driver must not send additional I/O requests to the I/O target until the reset request completes.

When a driver calls WdfRequestSend, the framework sends a URB_FUNCTION_RESET_PIPE request to the I/O target. For more information about resetting a USB pipe, see the USB specification.

You can forward an I/O request that your driver received in an I/O queue, or you can create and send a new request.

To forward an I/O request that your driver received in an I/O queue, specify the received request's handle for the WdfUsbTargetPipeFormatRequestForReset method's Request parameter.

To create a new I/O request, call WdfRequestCreate to preallocate a request object. Supply the request handle for the WdfUsbTargetPipeFormatRequestForReset method's Request parameter. You can reuse the request object by calling WdfRequestReuse. Your driver's EvtDriverDeviceAdd callback function can preallocate request objects for a device.

After calling WdfUsbTargetPipeFormatRequestForReset to format an I/O request, the driver must call WdfRequestSend to send the request (either synchronously or asynchronously) to an I/O target.

Multiple calls to WdfUsbTargetPipeFormatRequestForReset that use the same request do not cause additional resource allocations. Therefore, to reduce the chance that WdfRequestCreate will return STATUS_INSUFFICIENT_RESOURCES, your driver's EvtDriverDeviceAdd callback function can call WdfRequestCreate to preallocate one or more request objects for a device. The driver can subsequently reuse (call WdfRequestReuse), reformat (call WdfUsbTargetPipeFormatRequestForReset), and resend (call WdfRequestSend) each request object without risking a STATUS_INSUFFICIENT_RESOURCES return value from a later call to WdfRequestCreate. All subsequent calls to WdfUsbTargetPipeFormatRequestForReset for the reused request object will return STATUS_SUCCESS, if parameter values do not change. (If the driver does not call the same request-formatting method each time, additional resources might be allocated.)

For information about obtaining status information after an I/O request completes, see Obtaining Completion Information.

For more information about the WdfUsbTargetPipeFormatRequestForReset method and USB I/O targets, see USB I/O Targets.

Examples

The following code example formats a reset request for a USB pipe, registers a CompletionRoutine callback function, and sends the request.

status = WdfUsbTargetPipeFormatRequestForReset(
                                               pipe,
                                               Request
                                               );
if (!NT_SUCCESS(status)) {
    goto Exit;
}

WdfRequestSetCompletionRoutine(
                               Request,
                               AbortCompletionRoutine,
                               pipe
                               );

if (WdfRequestSend(
                   Request,
                   WdfUsbTargetPipeGetIoTarget(pipe),
                   WDF_NO_SEND_OPTIONS
                   ) == FALSE) {
    status = WdfRequestGetStatus(Request);
    goto Exit;
}
Exit:
if (!NT_SUCCESS(status)) {
    WdfRequestCompleteWithInformation(
                                      Request,
                                      status,
                                      0
                                      );
}
return;

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdfusb.h (include Wdfusb.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI compliance rules	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestForUrbXrb(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

Share via