IWDFUsbTargetFactory::CreateUsbTargetDevice method

The CreateUsbTargetDevice method creates a USB device object that is also an I/O target.

Syntax


HRESULT CreateUsbTargetDevice(
  [out]  IWDFUsbTargetDevice **ppDevice
);

Parameters

ppDevice [out]

A pointer to a buffer that receives a pointer to the IWDFUsbTargetDevice interface for the USB target device object.

Return value

CreateUsbTargetDevice returns one of the following values:

Return codeDescription
S_OK

CreateUsbTargetDevice successfully created a USB device object that is also an I/O target.

E_OUTOFMEMORY

CreateUsbTargetDevice encountered an allocation failure.

An error code that is defined in Winerror.h

This value corresponds to the error code that the WinUsb_Initialize function returned.

 

Remarks

A UMDF driver should release the IWDFUsbTargetDevice interface pointer that the CreateUsbTargetDevice method returns in the ppDevice parameter when the driver is done with the interface.

If the file object that is associated with the created I/O target object is required, the driver should call the IWDFIoTarget::GetTargetFile method. For more information about this file object, see File Creation by a USB I/O Target.

Note  CreateUsbTargetDevice inherits all of the methods of the IWDFIoTarget interface.

To use the newly created USB I/O target object in a device stack, the INF file that installs the UMDF driver must contain the UmdfDispatcher directive and set UmdfDispatcher to WinUsb (UmdfDispatcher=WinUsb) in the DDInstall.WDF section. UmdfDispatcher is required to inform the UMDF platform that it can allow access to the USB I/O target. For more information about UmdfDispatcher, see Specifying WDF Directives.

Examples

The following code example shows how to create and use a USB device object in an implementation of the UMDF driver's IPnpCallbackHardware::OnPrepareHardware method.


HRESULT
CUmdfHidDevice::OnPrepareHardware(
    __in IWDFDevice* WdfDevice
    )
{
    CComPtr<IWDFUsbTargetFactory> factory;
    USB_INTERFACE_DESCRIPTOR interfaceDescriptor;
    bool hidInterfaceFound = false;
    PUSB_HID_DESCRIPTOR hidDescriptor;
    NTSTATUS status;
    HRESULT hr = S_OK;
    //
    // Get the USB I/O target factory interface.
    //
    hr = WdfDevice->QueryInterface(IID_PPV_ARGS(&factory));
    //
    // Create the USB I/O target.
    //
    hr = factory->CreateUsbTargetDevice(&m_UsbTargetDevice);
    //
    // Get the configuration descriptor for the target device.
    //
    if (SUCCEEDED(hr))
    {
        hr = RetrieveConfigDescriptor(&m_ConfigDescriptor, 
                                      &m_ConfigDescriptorCb);
    }
    //
    // Iterate through the interfaces on the device and find the HID interface.
    //
    if (SUCCEEDED(hr))
    {
        CComPtr<IWDFUsbInterface> usbInterface;
        UCHAR index;
        bool found = true;
        for (index = 0; index < m_ConfigDescriptor->bNumInterfaces; index += 1)
        {
            hr = m_UsbTargetDevice->RetrieveUsbInterface(index, &usbInterface);
            if (SUCCEEDED(hr))
            {
                usbInterface->GetInterfaceDescriptor(&interfaceDescriptor);
                if (interfaceDescriptor.bInterfaceClass == 0x3)
                {
                    hidInterfaceFound = true;
                    break;
                }
            }
            else
            {
                break;
            }
        }
        if (SUCCEEDED(hr) && (hidInterfaceFound == false))
        {
            hr = E_FAIL;
        }
    }
    //
    // Get the HID descriptor associated with this interface.
    //
    if (SUCCEEDED(hr))
    {
        hr = ParseHidDescriptor(
                                m_ConfigDescriptor,
                                m_ConfigDescriptorCb,
                                interfaceDescriptor.bInterfaceNumber
                                );
    }
    //
    // Process the HID information from the device and setup 
    // the collection data structures.
    //
    if (SUCCEEDED(hr))
    {
        hr = SetupCollections();
    }
    return hr;
}

Requirements

End of support

Unavailable in UMDF 2.0 and later.

Minimum UMDF version

1.5

Header

Wudfusb.h (include Wudfusb.h)

DLL

WUDFx.dll

See also

IWDFUsbTargetFactory
WinUsb_Initialize
IWDFIoTarget
IWDFIoTarget::GetTargetFile
IWDFUsbTargetDevice

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft