Expand Minimize

WdfUsbTargetDeviceCreate method

[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

Device [in]

A handle to a framework device object.

Attributes [in, optional]

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.

UsbDevice [out]

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 codeDescription
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

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, KmdfIrql, KmdfIrql2, UsbDeviceCreate, UsbDeviceCreateFail, UsbDeviceCreateTarget, UsbKmdfIrql, UsbKmdfIrql2

See also

EvtDevicePrepareHardware
WDF_OBJECT_ATTRIBUTES
WdfUsbTargetDeviceGetNumInterfaces

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft