función USBD_CreateHandle (usbdlib.h)

Artículo
02/07/2025

Un controlador de cliente USB WDM llama a la rutina USBD_CreateHandle para obtener un controlador USBD. La rutina registra el controlador cliente con la pila de controladores USB subyacente.

Nota para controladores de Windows Driver Framework (WDF): Si el controlador cliente es un controlador basado en WDF, no necesita el controlador USBD. El controlador cliente se registra en su llamada al método WdfUsbTargetDeviceCreateWithParameters.

Sintaxis

NTSTATUS USBD_CreateHandle(
  [in]  PDEVICE_OBJECT DeviceObject,
  [in]  PDEVICE_OBJECT TargetDeviceObject,
  [in]  ULONG          USBDClientContractVersion,
  [in]  ULONG          PoolTag,
  [out] USBD_HANDLE    *USBDHandle
);

Parámetros

[in] DeviceObject

Puntero al objeto de dispositivo para el controlador cliente.

[in] TargetDeviceObject

Puntero al siguiente objeto de dispositivo inferior de la pila de dispositivos. El controlador cliente recibe un puntero a ese objeto de dispositivo en una llamada anterior a IoAttachDeviceToDeviceStack.

[in] USBDClientContractVersion

La versión del contrato que admite el controlador cliente. USBDClientContractVersion debe ser USBD_CLIENT_CONTRACT_VERSION_602. Para obtener más información, vea Comentarios.

[in] PoolTag

Etiqueta de grupo que se usa para las asignaciones de memoria.

[out] USBDHandle

Identificador opaco que indica que el controlador cliente se registró con la pila de controladores USB. Para obtener más información, vea Comentarios.

Valor devuelto

La rutina devuelve un código NTSTATUS. Entre los valores posibles se incluyen, entre otros, estos valores en la tabla siguiente.

Código devuelto	Descripción
STATUS_SUCCESS	La llamada de rutina se realizó correctamente.
STATUS_INVALID_LEVEL	El autor de la llamada no se ejecuta en el valor IRQL PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	El autor de la llamada pasó uno de los siguientes valores de parámetro no válidos: DeviceObject, TargetDeviceObjecto USBDHandle es NULL. El valor del contrato de cliente especificado en USBDClientContractVersion no es válido. PoolTag es cero.

Observaciones

Registro de versiones de

Windows 8 incluye una nueva pila de controladores USB para admitir dispositivos USB 3.0. La nueva pila de controladores USB proporciona varias funcionalidades nuevas, como compatibilidad con secuencias, MDL encadenadas, etc. Para que el controlador cliente pueda usar cualquiera de esas funcionalidades USB, debe registrar el controlador cliente con la pila del controlador USB y obtener un controlador USBD. El identificador es necesario para llamar a rutinas que usan o configuran las nuevas funcionalidades. Para obtener un identificador USBD, llame a USBD_CreateHandle.

El controlador cliente debe llamar a USBD_CreateHandle independientemente de si el dispositivo está conectado a un controlador host USB 3.0, 2.0 o 1.1. Si el dispositivo está conectado a un controlador de host USB 3.0, Windows carga la pila de controladores USB 3.0. De lo contrario, se carga la pila de controladores USB 2.0. En cualquier caso, el controlador de cliente no es necesario para conocer la versión compatible con la pila de controladores USB subyacente. USBD_CreateHandle evalúa la versión de la pila de controladores y asigna los recursos de forma adecuada.

El controlador cliente debe especificar USBD_CLIENT_CONTRACT_VERSION_602 en el parámetro USBDClientContractVersion y seguir el conjunto de reglas descritas en Procedimientos recomendados: Uso de direcciones URL.

llamada USBD_CreateHandle

Un controlador cliente de Windows Driver Model (WDM) debe llamar a la rutina USBD_CreateHandle antes de que el controlador envíe otras solicitudes, a través de direcciones URL o IOCTLs, a la pila del controlador USB. Normalmente, el controlador cliente obtiene el controlador USBD en su rutina AddDevice.

No se requiere un controlador cliente de Windows Driver Frameworks (WDF) para llamar a USBD_CreateHandle porque el marco llama a esta rutina en nombre del controlador cliente durante la fase de inicialización del dispositivo. En su lugar, el controlador cliente puede especificar su versión del contrato de cliente en la estructura WDF_USB_DEVICE_CREATE_CONFIG y pasarla en la llamada a WdfUsbTargetDeviceCreateWithParameters.

finalización de llamadas de USBD_CreateHandle

Si la llamada USBD_CreateHandle se realiza correctamente, se obtiene un controlador USBD válido en el parámetro USBDHandle. El controlador cliente debe usar el controlador USBD en las solicitudes futuras del controlador cliente a la pila del controlador USB.

Si se produce un error en la llamada USBD_CreateHandle, el controlador cliente puede producir un error en la rutina AddDevice.

Una vez que el controlador cliente haya terminado de usar el controlador USBD, el controlador debe cerrar el controlador llamando a la rutina USBD_CloseHandle.

Ejemplos

En el código de ejemplo siguiente se muestra cómo registrar un controlador cliente llamando a USBD_CreateHandle.

DRIVER_ADD_DEVICE MyAddDevice;

NTSTATUS MyAddDevice( __in PDRIVER_OBJECT  DriverObject,
                     __in PDEVICE_OBJECT  PhysicalDeviceObject)
{

    NTSTATUS            ntStatus;
    PDEVICE_OBJECT      deviceObject;
    PDEVICE_EXTENSION   deviceExtension;
    PDEVICE_OBJECT      stackDeviceObject;
    USBD_HANDLE         usbdHandle;

    ...

        ntStatus = IoCreateDevice(DriverObject,
        sizeof(DEVICE_EXTENSION),
        NULL,
        FILE_DEVICE_UNKNOWN,
        FILE_AUTOGENERATED_DEVICE_NAME,
        FALSE,
        &deviceObject);


    if (!NT_SUCCESS(ntStatus)) 
    {
        return ntStatus;
    }

    ...

        //     Attach the FDO to the top of the PDO in the client driver's 
        //  device stack.

        deviceExtension->StackDeviceObject = IoAttachDeviceToDeviceStack (
        deviceObject,
        PhysicalDeviceObject);

    ...

        // Initialize the DeviceExtension

        deviceExtension = deviceObject->DeviceExtension;

    ...

        //Register the client driver with the USB driver stack.
        //Obtain a USBD handle for registration.

        ntStatus = USBD_CreateHandle(deviceObject, 
        deviceExtension->StackDeviceObject,
        USBD_CLIENT_CONTRACT_VERSION_602,
        POOL_TAG,
        &deviceExtension->USBDHandle);

    if (!NT_SUCCESS(ntStatus)) 
    {
        return ntStatus;
    }

    ...

        // Call USBD_QueryUsbCapability to determine 
        // stream support. 

        ntStatus = USBD_QueryUsbCapability ( deviceExtension->USBDHandle,  
        (GUID*)&GUID_USB_CAPABILITY_STATIC_STREAMS,  
        sizeof(ULONG),  
        (PUCHAR) &deviceExtension.MaxSupportedStreams);  


    if (!NT_SUCCESS(ntStatus)) 
    {
        deviceExtension->MaxSupportedStreams = 0;
        ntStatus = STATUS_SUCCESS;
    } 

    ...

}

Requisitos

Requisito	Valor
cliente mínimo admitido	Requiere WDK para Windows 8. Tiene como destino Windows Vista y versiones posteriores del sistema operativo Windows.
de la plataforma de destino de	Escritorio
encabezado de	usbdlib.h (include usbdlib.h, usb.h)
biblioteca de	Usbdex.lib; Ntstrsafe.lib
irQL	PASSIVE_LEVEL

Consulte también

asignar y crear direcciones URL

Procedimientos recomendados de : Uso de direcciones URL

USBD_CloseHandle

Compartir a través de