WdfUsbTargetDeviceCreateWithParameters function (wdfusb.h)

Article
04/18/2022

[Applies to KMDF and UMDF]

The WdfUsbTargetDeviceCreateWithParameters method creates a framework USB device object for a specified framework device object and opens the USB device for I/O operations. The method also specifies configuration information for the framework USB device object.

Syntax

NTSTATUS WdfUsbTargetDeviceCreateWithParameters(
  [in]           WDFDEVICE                     Device,
  [in]           PWDF_USB_DEVICE_CREATE_CONFIG Config,
  [in, optional] PWDF_OBJECT_ATTRIBUTES        Attributes,
  [out]          WDFUSBDEVICE                  *UsbDevice
);

Parameters

[in] Device

A handle to a framework device object.

[in] Config

A pointer to a WDF_USB_DEVICE_CREATE_CONFIG structure that contains configuration information for the framework USB device object.

[in, optional] Attributes

A pointer to a caller-supplied WDF_OBJECT_ATTRIBUTES structure that contains attributes for the new framework USB device object. (The structure's ParentObject member must be NULL.) This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES.

[out] UsbDevice

A pointer to a location that receives a handle to the new framework USB device object.

Return value

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

Return code	Description
STATUS_INFO_LENGTH_MISMATCH	The Config parameter is not the correct size.
STATUS_INSUFFICIENT_RESOURCES	There was insufficient memory to create a new framework USB device object.
STATUS_INVALID_PARAMETER	An invalid parameter was detected. See the Remarks section for more information.
STATUS_UNSUCCESSFUL	An attempt to get USB configuration information failed.

For a list of other return values that the WdfUsbTargetDeviceCreateWithParameters method might return, see Framework Object Creation Errors.

This method also might return other NTSTATUS values.

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

Remarks

Windows 8 includes a new USB driver stack to support USB 3.0 devices.

Before a framework-based client driver can use the new capabilities of the USB driver stack for Windows 8, the driver must register itself with the underlying USB driver stack that is loaded by Windows for the device. To register the client driver, call WdfUsbTargetDeviceCreateWithParameters and specify a contract version in the WDF_USB_DEVICE_CREATE_CONFIG structure.

If the client driver is intended to build, run, and use the improvements and the new capabilities on Windows 8, the client contract version is USBD_CLIENT_CONTRACT_VERSION_602.

Typically, drivers call WdfUsbTargetDeviceCreateWithParameters from within an EvtDevicePrepareHardware callback function. Drivers can also call WdfUsbTargetDeviceCreateWithParameters from within an EvtDriverDeviceAdd callback function.

For information about how WDM USB client drivers interact with the USB 3.0 driver stack, see Best Practices: Using URBs.

If the driver calls WdfUsbTargetDeviceCreateWithParameters to create a framework USB device object, the driver must create URBs only by calling WdfUsbTargetDeviceCreateUrb or WdfUsbTargetDeviceCreateIsochUrb.

If you call this method from a UMDF driver, you must specify the UmdfDispatcher directive in the driver's INF file. Otherwise, this method may return STATUS_INVALID_PARAMETER. For more information about this directive, see Specifying WDF Directives in INF Files.

Examples

The following code example is part of an EvtDevicePrepareHardware callback function that calls WdfUsbTargetDeviceCreateWithParameters. The example stores the handle to the framework USB device object in driver-defined context space.

NTSTATUS
MyEvtDevicePrepareHardware(
    IN WDFDEVICE  Device,
    IN WDFCMRESLIST  ResourceList,
    IN WDFCMRESLIST  ResourceListTranslated
    )
{
    NTSTATUS  status;
    PMY_DEVICE_CONTEXT  pMyDeviceContext;
    WDF_USB_DEVICE_CREATE_CONFIG  Config;

    pMyDeviceContext = GetDeviceContext(Device);

    // If object handle is not NULL, MyEvtDevicePrepareHardware
    // was called previously and the handle is still valid.
    if (pMyDeviceContext->UsbDevice != NULL) {
        return STATUS_SUCCESS;
    }

    WDF_USB_DEVICE_CREATE_CONFIG_INIT(
                                      &Config,
                                      USBD_CLIENT_CONTRACT_VERSION_602
                                      );

    status = WdfUsbTargetDeviceCreateWithParameters(
                                      Device,
                                      &Config,
                                      WDF_NO_OBJECT_ATTRIBUTES,
                                      &pMyDeviceContext->UsbDevice
                                      );
    if (!NT_SUCCESS(status)) {
        return status;
    }
...
}

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.11
Minimum UMDF version	2.0
Header	wdfusb.h (include Wdfusb.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI compliance rules	DriverCreate(kmdf), RequestForUrbXrb(kmdf), UsbDeviceCreate(kmdf), UsbDeviceCreateFail(kmdf), UsbDeviceCreateTarget(kmdf)