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 de WDF_USB_DEVICE_CREATE_CONFIG que contiene información de configuración para el objeto de dispositivo USB 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 del marco. (El miembro parentObject de la estructura debe ser NULL). Este parámetro es opcional y se puede WDF_NO_OBJECT_ATTRIBUTES.
[out] UsbDevice
Puntero a una ubicación que recibe un identificador del nuevo objeto de dispositivo USB del 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 siguientes valores:
| Código devuelto | Descripción |
|---|---|
|
El parámetro Config no es el tamaño correcto. |
|
No había memoria suficiente para crear un nuevo objeto de dispositivo USB de marco. |
|
Se detectó un parámetro no válido. Consulte la sección Comentarios para obtener más información. |
|
Error al intentar obtener información de configuración de USB. |
Para obtener una lista de otros valores devueltos que puede devolver el método WdfUsbTargetDeviceCreateWithParameters, vea errores de creación de objetos de Framework.
Este método también puede devolver otros valores de NTSTATUS.
Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.
Observaciones
Windows 8 incluye una nueva pila de controladores USB para admitir dispositivos USB 3.0.
Para que un controlador de cliente basado en marcos 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 en Windows 8, la versión del contrato de cliente es USBD_CLIENT_CONTRACT_VERSION_602.
Normalmente, los controladores llaman a WdfUsbTargetDeviceCreateWithParameters desde un EvtDevicePrepareHardware función de devolución de llamada. 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 Especificación de directivas WDF en archivos INF.
Ejemplos
El ejemplo de código siguiente forma parte de una función de devolución de llamada EvtDevicePrepareHardware que llama a WdfUsbTargetDeviceCreateWithParameters. En el ejemplo se almacena el identificador del 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 | Valor |
|---|---|
| de la plataforma de destino de | Universal |
| versión mínima de KMDF | 1.11 |
| versión mínima de UMDF | 2.0 |
| encabezado de | wdfusb.h (incluya Wdfusb.h) |
| biblioteca de | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| irQL | PASSIVE_LEVEL |
| reglas de cumplimiento de DDI | DriverCreate(kmdf), RequestForUrbXrb(kmdf), UsbDeviceCreate(kmdf), UsbDeviceCreateFail(kmdf), UsbDeviceCreateTarget(kmdf) |