WdfUsbTargetPipeResetSynchronously - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers
// wdfusb.h

NTSTATUS WdfUsbTargetPipeResetSynchronously(
  [in]           WDFUSBPIPE                Pipe,
  [in, optional] WDFREQUEST                Request,
  [in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions
);

View the official Windows Driver Kit DDI reference

NtDoc

No description available.

Windows Driver Kit DDI reference (nf-wdfusb-wdfusbtargetpiperesetsynchronously)

WdfUsbTargetPipeResetSynchronously function

Description

[Applies to KMDF and UMDF]

The WdfUsbTargetPipeResetSynchronously method builds a reset request and sends it synchronously to a specified USB pipe.

Parameters

Pipe [in]

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

Request [in, optional]

A handle to a framework request object. This parameter is optional and can be NULL. For more information, see the following Remarks section.

RequestOptions [in, optional]

A pointer to a caller-allocated WDF_REQUEST_SEND_OPTIONS structure that specifies options for the request. This pointer is optional and can be NULL. For more information, see the following Remarks section.

Return value

WdfUsbTargetPipeResetSynchronously 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_INFO_LENGTH_MISMATCH The size of the WDF_REQUEST_SEND_OPTIONS structure that the RequestOptions parameter specified was incorrect.
STATUS_INVALID_PARAMETER An invalid parameter was detected.
STATUS_INSUFFICIENT_RESOURCES Insufficient memory was available.
STATUS_INVALID_DEVICE_REQUEST The caller's IRQL was not PASSIVE_LEVEL, or the I/O request that the Request parameter specified was already queued to an I/O target.
STATUS_IO_TIMEOUT The driver supplied a time-out value and the request did not complete within the allotted time.
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 the WdfUsbTargetPipeResetSynchronously method to send a USB reset request synchronously. To send such requests asynchronously use WdfUsbTargetPipeFormatRequestForReset, followed by WdfRequestSend.

Before the framework resets the I/O target's USB pipe, it cancels all I/O requests that remain in the I/O target's queue. The driver must not send additional I/O requests to the I/O target until WdfUsbTargetPipeResetSynchronously returns.

The driver must call WdfIoTargetStop before it calls WdfUsbTargetPipeResetSynchronously. After WdfUsbTargetPipeResetSynchronously returns, the driver can call WdfIoTargetStart.

When a driver calls WdfUsbTargetPipeResetSynchronously, 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.

The WdfUsbTargetPipeResetSynchronously method does not return until the request has completed, unless the driver supplies a time-out value in the WDF_REQUEST_SEND_OPTIONS structure that the RequestOptions parameter points to, or unless an error is detected.

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 WdfUsbTargetPipeResetSynchronously method's Request parameter.

To create and send a new request, either supply a NULL request handle for the Request parameter, or create a new request object and supply its handle:

Your driver can specify a non-NULL RequestOptions parameter, whether the driver provides a non-NULL or a NULL Request parameter. You can, for example, use the RequestOptions parameter to specify a time-out value.

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

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

Examples

The following code example sends a reset request to a USB device's pipe.

NTSTATUS  status;

status = WdfUsbTargetPipeResetSynchronously(
                                            Pipe,
                                            WDF_NO_HANDLE,
                                            NULL
                                            );

See also

WdfObjectDereference

WdfRequestCancelSentRequest

WdfRequestSend

WdfUsbTargetPipeAbortSynchronously