Función WdfUsbTargetDeviceCreateWithParameters (wdfusb.h)

[Se aplica a KMDF y UMDF]

El método WdfUsbTargetDeviceCreateWithParameters crea un objeto de dispositivo USB de marco para un objeto de dispositivo de marco especificado y abre el dispositivo USB para las operaciones de E/S. El método también especifica información de configuración para el objeto de dispositivo USB del marco.

Sintaxis

NTSTATUS WdfUsbTargetDeviceCreateWithParameters(
  [in]           WDFDEVICE                     Device,
  [in]           PWDF_USB_DEVICE_CREATE_CONFIG Config,
  [in, optional] PWDF_OBJECT_ATTRIBUTES        Attributes,
  [out]          WDFUSBDEVICE                  *UsbDevice
);

Parámetros

[in] Device

Identificador de un objeto de dispositivo de marco.

[in] Config

Puntero a una estructura WDF_USB_DEVICE_CREATE_CONFIG que contiene información de configuración para el objeto de dispositivo USB del marco.

[in, optional] Attributes

Puntero a una estructura de WDF_OBJECT_ATTRIBUTES proporcionada por el autor de la llamada que contiene atributos para el nuevo objeto de dispositivo USB de marco. (El miembro ParentObject de la estructura debe ser NULL). Este parámetro es opcional y puede ser WDF_NO_OBJECT_ATTRIBUTES.

[out] UsbDevice

Puntero a una ubicación que recibe un identificador para el nuevo objeto de dispositivo USB de marco.

Valor devuelto

WdfUsbTargetDeviceCreateWithParameters devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, este método puede devolver uno de los valores siguientes:

Código devuelto	Descripción
STATUS_INFO_LENGTH_MISMATCH	El parámetro Config no es el tamaño correcto.
STATUS_INSUFFICIENT_RESOURCES	No había memoria suficiente para crear un nuevo objeto de dispositivo USB de marco.
STATUS_INVALID_PARAMETER	Se ha detectado un parámetro no válido. Vea la sección Comentarios para obtener más información.
STATUS_UNSUCCESSFUL	Error al intentar obtener información de configuración USB.

 

Para obtener una lista de otros valores devueltos que puede devolver el método WdfUsbTargetDeviceCreateWithParameters , vea Errores de creación de objetos de marco.

Este método también podría devolver otros valores NTSTATUS.

Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.

Comentarios

Windows 8 incluye una nueva pila de controladores USB para admitir dispositivos USB 3.0.

Antes de que un controlador de cliente basado en marco pueda usar las nuevas funcionalidades de la pila de controladores USB para Windows 8, el controlador debe registrarse con la pila de controladores USB subyacente que Windows carga para el dispositivo. Para registrar el controlador cliente, llame a WdfUsbTargetDeviceCreateWithParameters y especifique una versión del contrato en la estructura WDF_USB_DEVICE_CREATE_CONFIG .

Si el controlador cliente está diseñado para compilar, ejecutar y usar las mejoras y las nuevas funcionalidades de Windows 8, la versión del contrato de cliente se USBD_CLIENT_CONTRACT_VERSION_602.

Normalmente, los controladores llaman a WdfUsbTargetDeviceCreateWithParameters desde una función de devolución de llamada EvtDevicePrepareHardware . Los controladores también pueden llamar a WdfUsbTargetDeviceCreateWithParameters desde una función de devolución de llamada EvtDriverDeviceAdd .

Para obtener información sobre cómo interactúan los controladores de cliente USB WDM con la pila de controladores USB 3.0, consulte Procedimientos recomendados: Uso de direcciones URL.

Si el controlador llama a WdfUsbTargetDeviceCreateWithParameters para crear un objeto de dispositivo USB de marco, el controlador solo debe crear direcciones URL llamando a WdfUsbTargetDeviceCreateUrb o WdfUsbTargetDeviceCreateIsochUrb.

Si llama a este método desde un controlador UMDF, debe especificar la directiva UmdfDispatcher en el archivo INF del controlador. De lo contrario, este método puede devolver STATUS_INVALID_PARAMETER. Para obtener más información sobre esta directiva, vea Especificar directivas WDF en archivos INF.

Ejemplos

El siguiente ejemplo de código forma parte de una función de devolución de llamada EvtDevicePrepareHardware que llama a WdfUsbTargetDeviceCreateWithParameters. En el ejemplo se almacena el identificador en el objeto de dispositivo USB del marco en el espacio de contexto definido por el controlador.

NTSTATUS
MyEvtDevicePrepareHardware(
    IN WDFDEVICE  Device,
    IN WDFCMRESLIST  ResourceList,
    IN WDFCMRESLIST  ResourceListTranslated
    )
{
    NTSTATUS  status;
    PMY_DEVICE_CONTEXT  pMyDeviceContext;
    WDF_USB_DEVICE_CREATE_CONFIG  Config;

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

    WDF_USB_DEVICE_CREATE_CONFIG_INIT(
                                      &Config,
                                      USBD_CLIENT_CONTRACT_VERSION_602
                                      );

    status = WdfUsbTargetDeviceCreateWithParameters(
                                      Device,
                                      &Config,
                                      WDF_NO_OBJECT_ATTRIBUTES,
                                      &pMyDeviceContext->UsbDevice
                                      );
    if (!NT_SUCCESS(status)) {
        return status;
    }
...
}

Requisitos

Requisito	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.11
Versión mínima de UMDF	2.0
Encabezado	wdfusb.h (incluya Wdfusb.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de DDI	DriverCreate(kmdf), RequestForUrbXrb(kmdf), UsbDeviceCreate(kmdf), UsbDeviceCreateFail(kmdf), UsbDeviceCreateTarget(kmdf)

Consulte también

USBD_CreateHandle

WDF_USB_DEVICE_CREATE_CONFIG

WDF_USB_DEVICE_CREATE_CONFIG_INIT

WdfUsbTargetDeviceCreate