Metodo IWDFUsbTargetFactory::CreateUsbTargetDevice (wudfusb.h)

Articolo
02/27/2024

[Avviso: UMDF 2 è la versione più recente di UMDF e sostituisce UMDF 1. Tutti i nuovi driver UMDF devono essere scritti usando UMDF 2. Nessuna nuova funzionalità viene aggiunta 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, vedere Introduzione con 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 ha creato correttamente un oggetto dispositivo USB che è anche una destinazione di I/O.
E_OUTOFMEMORY	CreateUsbTargetDevice ha rilevato un errore di allocazione.
Codice di errore definito in Winerror.h	Questo valore corrisponde al codice di errore restituito dalla funzione WinUsb_Initialize .

Commenti

Un driver UMDF deve rilasciare il puntatore dell'interfaccia IWDFUsbTargetDevice restituito dal metodo CreateUsbTargetDevice nel parametro ppDevice al termine del driver 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 in base a una destinazione di I/O USB.

NotaCreateUsbTargetDevice eredita tutti i metodi dell'interfaccia IWDFIoTarget .

Per usare l'oggetto di destinazione USB I/O 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.

Esempio

Nell'esempio di codice seguente viene illustrato come creare e usare un oggetto dispositivo USB in un'implementazione del metodo IPnpCallbackHardware del driver UMDF::OnPrepareHardware .

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

Requisiti

Requisito	Valore
Fine del supporto	Non disponibile in UMDF 2.0 e versioni successive.
Piattaforma di destinazione	Desktop
Versione UMDF minima	1.5
Intestazione	wudfusb.h (include Wudfusb.h)
DLL	WUDFx.dll