Método IWDFUsbTargetFactory::CreateUsbTargetDevice (wudfusb.h)

Artículo
08/08/2023

[Advertencia: UMDF 2 es la versión más reciente de UMDF y sustituye a UMDF 1. Todos los controladores UMDF nuevos deben escribirse con UMDF 2. No se agregan nuevas características a UMDF 1 y hay compatibilidad limitada con UMDF 1 en versiones más recientes de Windows 10. Los controladores universales de Windows deben usar UMDF 2. Para obtener más información, consulta Introducción con UMDF.

El método CreateUsbTargetDevice crea un objeto de dispositivo USB que también es un destino de E/S.

Sintaxis

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

Parámetros

[out] ppDevice

Puntero a un búfer que recibe un puntero a la interfaz IWDFUsbTargetDevice para el objeto de dispositivo de destino USB.

Valor devuelto

CreateUsbTargetDevice devuelve uno de los siguientes valores:

Código devuelto	Descripción
S_OK	CreateUsbTargetDevice creó correctamente un objeto de dispositivo USB que también es un destino de E/S.
E_OUTOFMEMORY	CreateUsbTargetDevice encontró un error de asignación.
Código de error definido en Winerror.h	Este valor corresponde al código de error que devolvió la función WinUsb_Initialize .

Comentarios

Un controlador UMDF debe liberar el puntero de interfaz IWDFUsbTargetDevice que el método CreateUsbTargetDevice devuelve en el parámetro ppDevice cuando el controlador se realiza con la interfaz .

Si se requiere el objeto de archivo asociado al objeto de destino de E/S creado, el controlador debe llamar al método IWDFIoTarget::GetTargetFile . Para obtener más información sobre este objeto de archivo, vea Creación de archivos mediante un destino de E/S USB.

NotaCreateUsbTargetDevice hereda todos los métodos de la interfaz IWDFIoTarget .

Para usar el objeto de destino de E/S USB recién creado en una pila de dispositivos, el archivo INF que instala el controlador UMDF debe contener la directiva UmdfDispatcher y establecer UmdfDispatcher en WinUsb (UmdfDispatcher=WinUsb) en la sección DDInstall.WDF . UmdfDispatcher es necesario para informar a la plataforma UMDF de que puede permitir el acceso al destino de E/S USB. Para obtener más información sobre UmdfDispatcher, vea Especificar directivas WDF.

Ejemplos

En el ejemplo de código siguiente se muestra cómo crear y usar un objeto de dispositivo USB en una implementación del método IPnpCallbackHardware del controlador 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;
}

Requisitos

Requisito	Value
Finalización del soporte técnico	No disponible en UMDF 2.0 y versiones posteriores.
Plataforma de destino	Escritorio
Versión mínima de UMDF	1.5
Encabezado	wudfusb.h (incluya Wudfusb.h)
Archivo DLL	WUDFx.dll