WdfUsbTargetDeviceCreate function (wdfusb.h)

Article
04/18/2022

[Applies to KMDF and UMDF]

The WdfUsbTargetDeviceCreate method creates a framework USB device object for a specified framework device object and opens the USB device for I/O operations.

Note If you are building your driver using KMDF 1.11 or UMDF 2.0, or later, we recommend that you call WdfUsbTargetDeviceCreateWithParameters instead of WdfUsbTargetDeviceCreate.

Syntax

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

Parameters

[in] Device

A handle to a framework device object.

[in, optional] Attributes

A pointer to a caller-supplied WDF_OBJECT_ATTRIBUTES structure that contains attributes for the new 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

WdfUsbTargetDeviceCreate returns STATUS_SUCCESS 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	There was insufficient memory to create a new USB device object.
STATUS_UNSUCCESSFUL	An attempt to get USB configuration information failed.

For a list of other return values that the WdfUsbTargetDeviceCreate 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

A driver that uses a USB I/O target must call WdfUsbTargetDeviceCreate after its device enters its working (D0) state. Typically, a driver calls WdfUsbTargetDeviceCreate from within its EvtDevicePrepareHardware callback function. (The driver cannot call WdfUsbTargetDeviceCreate from within its EvtDriverDeviceAdd callback function.)

WdfUsbTargetDeviceCreate obtains the USB device descriptor and the first USB configuration descriptor from the device and stores them. It also creates a framework USB interface object for each interface in the device's first configuration. To determine the number of interfaces that the configuration supports, the driver can call WdfUsbTargetDeviceGetNumInterfaces.

After calling WdfUsbTargetDeviceCreate, your driver can call additional framework USB device object methods.

The parent of each USB device object is the driver's framework driver object. The driver cannot change this parent, and the ParentObject member or the WDF_OBJECT_ATTRIBUTES structure must be NULL.

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

Examples

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

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

    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;
    }
 status = WdfUsbTargetDeviceCreate(
                                      Device,
                                      WDF_NO_OBJECT_ATTRIBUTES,
                                      &pMyDeviceContext->UsbDevice
                                      );
    if (!NT_SUCCESS(status)) {
        return status;
    }
...
}

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	PASSIVE_LEVEL
DDI compliance rules	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbDeviceCreate(kmdf), UsbDeviceCreateFail(kmdf), UsbDeviceCreateTarget(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

Share via