WdfUsbTargetDeviceSendUrbSynchronously - NtDoc

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

NTSTATUS WdfUsbTargetDeviceSendUrbSynchronously(
  [in]           WDFUSBDEVICE              UsbDevice,
  [in, optional] WDFREQUEST                Request,
  [in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [in]           PURB                      Urb
);

View the official Windows Driver Kit DDI reference

NtDoc

No description available.

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

WdfUsbTargetDeviceSendUrbSynchronously function

Description

[Applies to KMDF only]

The WdfUsbTargetDeviceSendUrbSynchronously method sends a USB request synchronously to a specified USB device, using request parameters that are described by a URB.

Parameters

UsbDevice [in]

A handle to a USB device object that was obtained from a previous call to WdfUsbTargetDeviceCreateWithParameters.

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.

Urb [in]

A pointer to a caller-initialized URB structure.

If the driver previously called WdfUsbTargetDeviceCreateWithParameters to create UsbDevice, the driver must use WdfUsbTargetDeviceCreateUrb or WdfUsbTargetDeviceCreateIsochUrb to create this URB.

Return value

WdfUsbTargetDeviceSendUrbSynchronously returns the 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_INVALID_DEVICE_REQUEST The caller's IRQL was invalid.
STATUS_INSUFFICIENT_RESOURCES Insufficient memory was available.
STATUS_IO_TIMEOUT The driver supplied a time-out value and the request did not complete within the allotted time.

This method also might return other NTSTATUS values.

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

Remarks

Use the WdfUsbTargetDeviceSendUrbSynchronously method to send a USB control transfer request synchronously. To send such requests asynchronously, use WdfUsbTargetDeviceFormatRequestForUrb, followed by WdfRequestSend.

The WdfUsbTargetDeviceSendUrbSynchronously method does not return until the request has completed, unless the driver supplies a time-out value in the RequestOptions parameter's WDF_REQUEST_SEND_OPTIONS structure, 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 WdfUsbTargetDeviceSendUrbSynchronously 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 WdfUsbTargetDeviceSendUrbSynchronously method and USB I/O targets, see USB I/O Targets.

Examples

The following code example initializes a URB structure and calls WdfUsbTargetDeviceSendUrbSynchronously.

URB Urb;
NTSTATUS status;

Urb.UrbHeader.Function =  URB_FUNCTION_GET_CONFIGURATION;
Urb.UrbHeader.Length = sizeof(struct _URB_CONTROL_GET_CONFIGURATION_REQUEST);
Urb.UrbControlGetConfigurationRequest.TransferBufferLength = 1 ; // Must be 1
Urb.UrbControlGetConfigurationRequest.TransferBufferMDL = NULL;
Urb.UrbControlGetConfigurationRequest.TransferBuffer = outBuffer;
Urb.UrbControlGetConfigurationRequest.UrbLink = NULL;

status = WdfUsbTargetDeviceSendUrbSynchronously(
                                                UsbDevice,
                                                NULL,
                                                NULL,
                                                &Urb
                                                );

See also

EvtDriverDeviceAdd

WDF_REQUEST_SEND_OPTIONS

WdfRequestCancelSentRequest

WdfRequestCreate

WdfRequestReuse

WdfRequestSend

WdfUsbTargetDeviceFormatRequestForUrb