Función WdfUsbTargetDeviceCreate (wdfusb.h)

  • Artículo

[Se aplica a KMDF y UMDF]

El método WdfUsbTargetDeviceCreate 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.

Nota Si va a compilar el controlador mediante KMDF 1.11 o UMDF 2.0, o una versión posterior, se recomienda llamar a WdfUsbTargetDeviceCreateWithParameters en lugar de WdfUsbTargetDeviceCreate.
 

Sintaxis

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

Parámetros

[in] Device

Identificador de un objeto de dispositivo de 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. (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

WdfUsbTargetDeviceCreate 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_INVALID_PARAMETER
 Se ha detectado un parámetro no válido.
STATUS_INSUFFICIENT_RESOURCES
 No había memoria suficiente para crear un nuevo objeto de dispositivo USB.
STATUS_UNSUCCESSFUL
 Error al intentar obtener información de configuración USB.
 

Para obtener una lista de otros valores devueltos que el método WdfUsbTargetDeviceCreate podría devolver, 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

Un controlador que usa un destino de E/S USB debe llamar a WdfUsbTargetDeviceCreate después de que su dispositivo entre en estado de funcionamiento (D0). Normalmente, un controlador llama a WdfUsbTargetDeviceCreate desde su función de devolución de llamada EvtDevicePrepareHardware . (El controlador no puede llamar a WdfUsbTargetDeviceCreate desde su función de devolución de llamada EvtDriverDeviceAdd ).

WdfUsbTargetDeviceCreate obtiene el descriptor del dispositivo USB y el primer descriptor de configuración USB del dispositivo y los almacena. También crea un objeto de interfaz USB de marco para cada interfaz en la primera configuración del dispositivo. Para determinar el número de interfaces que admite la configuración, el controlador puede llamar a WdfUsbTargetDeviceGetNumInterfaces.

Después de llamar a WdfUsbTargetDeviceCreate, el controlador puede llamar a métodos de objeto de dispositivo USB de marco adicionales.

El elemento primario de cada objeto de dispositivo USB es el objeto de controlador de marco del controlador. El controlador no puede cambiar este elemento primario y el miembro ParentObject o la estructura WDF_OBJECT_ATTRIBUTES deben ser NULL.

Para obtener más información sobre el método WdfUsbTargetDeviceCreate y los destinos de E/S USB, consulte Destinos de E/S USB.

Ejemplos

El siguiente ejemplo de código forma parte de una función de devolución de llamada EvtDevicePrepareHardware que llama a WdfUsbTargetDeviceCreate. En el ejemplo se almacena el identificador del objeto del dispositivo USB 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;

    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;
    }
 status = WdfUsbTargetDeviceCreate(
                                      Device,
                                      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.0
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), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbDeviceCreate(kmdf), UsbDeviceCreateFail(kmdf), UsbDeviceCreateTarget(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

Consulte también

EvtDevicePrepareHardware

WDF_OBJECT_ATTRIBUTES

WdfUsbTargetDeviceGetNumInterfaces