función USBD_CreateHandle (usbdlib.h)

  • Artículo

Un controlador de cliente USB WDM llama a la rutina USBD_CreateHandle para obtener un identificador 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 de 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 la sección Comentarios.

[in] PoolTag

Etiqueta de grupo usada 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 la sección 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, TargetDeviceObject o USBDHandle es NULL.
  • El valor del contrato de cliente especificado en USBDClientContractVersion no es válido.
  • PoolTag es cero.

Comentarios

Registro de versiones

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 de controladores 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 de host USB 3.0, 2.0 o 1.1. Si el dispositivo está conectado a un controlador 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, no es necesario que el controlador cliente conozca 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.

Llamar a USBD_CreateHandle

El controlador cliente del modelo de controlador de Windows (WDM) debe llamar a la rutina USBD_CreateHandle antes de que el controlador envíe cualquier otra solicitud, a través de direcciones URL o IOCTLs, a la pila del controlador USB. Normalmente, el controlador cliente obtiene el identificador USBD en su rutina AddDevice.

No es necesario que un controlador cliente de Windows Driver Frameworks (WDF) llame 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 a la llamada a WdfUsbTargetDeviceCreateWithParameters.

finalización de llamadas de USBD_CreateHandle

Si la llamada USBD_CreateHandle se realiza correctamente, se obtiene un identificador USBD válido en el parámetro USBDHandle . El controlador cliente debe usar el controlador USBD en las futuras solicitudes del controlador cliente a la pila de controladores 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 identificador llamando a la rutina de USBD_CloseHandle .

Ejemplos

En el código de ejemplo siguiente se muestra cómo registrar un controlador de 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 Value
Cliente mínimo compatible Requiere WDK para Windows 8. Tiene como destino Windows Vista y versiones posteriores del sistema operativo Windows.
Plataforma de destino Escritorio
Encabezado usbdlib.h (include usbdlib.h, usb.h)
Library Usbdex.lib; Ntstrsafe.lib
IRQL PASSIVE_LEVEL

Consulte también

Asignar y compilar direcciones URL

Procedimientos recomendados: Uso de direcciones URL

USBD_CloseHandle