Metodo IWDFUsbTargetFactory::CreateUsbTargetDevice (wudfusb.h)

Articolo
02/07/2025

[Avviso: UMDF 2 è la versione più recente di UMDF e sostituisce UMDF 1. Tutti i nuovi driver UMDF devono essere scritti usando UMDF 2. Non vengono aggiunte nuove funzionalità a UMDF 1 ed è disponibile un supporto limitato per UMDF 1 nelle versioni più recenti di Windows 10. I driver di Windows universali devono usare UMDF 2. Per altre informazioni, vedi Introduzione a UMDF.]

Il metodo CreateUsbTargetDevice crea un oggetto dispositivo USB che è anche una destinazione di I/O.

Sintassi

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

Parametri

[out] ppDevice

Puntatore a un buffer che riceve un puntatore all'interfaccia IWDFUsbTargetDevice per l'oggetto dispositivo di destinazione USB.

Valore restituito

CreateUsbTargetDevice restituisce uno dei valori seguenti:

Codice restituito	Descrizione
S_OK	CreateUsbTargetDevice creato correttamente un oggetto dispositivo USB che è anche una destinazione di I/O.
E_OUTOFMEMORY	CreateUsbTargetDevice rilevato un errore di allocazione.
Codice di errore definito in Winerror.h	Questo valore corrisponde al codice di errore restituito dalla funzione WinUsb_Initialize.

Osservazioni

Un driver UMDF deve rilasciare il puntatore a interfaccia IWDFUsbTargetDevice restituito dal metodo CreateUsbTargetDevice nel parametro ppDevice quando il driver viene eseguito con l'interfaccia.

Se è necessario l'oggetto file associato all'oggetto di destinazione I/O creato, il driver deve chiamare il metodo IWDFIoTarget::GetTargetFile. Per altre informazioni su questo oggetto file, vedere creazione di file da una destinazione di I/O USB.

NotaCreateUsbTargetDevice eredita tutti i metodi dell 'interfaccia IWDFIoTarget.

Per usare l'oggetto di destinazione I/O USB appena creato in uno stack di dispositivi, il file INF che installa il driver UMDF deve contenere la direttiva UmdfDispatcher e impostare UmdfDispatcher su WinUsb (UmdfDispatcher=WinUsb) nella sezione DDInstall.WDF. UmdfDispatcher è necessario per informare la piattaforma UMDF che può consentire l'accesso alla destinazione di I/O USB. Per altre informazioni su UmdfDispatcher, vedere Specifica delle direttive WDF.

Esempi

L'esempio di codice seguente illustra come creare e usare un oggetto dispositivo USB in un'implementazione del metodo IPnpCallbackHardware::OnPrepare Hardware del driver UMDF.

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;
}

Fabbisogno

Requisito	Valore
Fine del supporto	Non disponibile in UMDF 2.0 e versioni successive.
piattaforma di destinazione	Desktop
versione minima di UMDF	1.5
intestazione	wudfusb.h (include Wudfusb.h)
dll	WUDFx.dll