USBD_CreateHandle 函数 (usbdlib.h)

  • 项目

USBD_CreateHandle例程由 WDM USB 客户端驱动程序调用，以获取 USBD 句柄。 例程将客户端驱动程序注册到基础 USB 驱动程序堆栈。

Windows 驱动程序框架 (WDF) 驱动程序的说明： 如果客户端驱动程序是基于 WDF 的驱动程序，则不需要 USBD 句柄。 客户端驱动程序在调用 WdfUsbTargetDeviceCreateWithParameters 方法时注册。

语法

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

参数

[in] DeviceObject

指向客户端驱动程序的设备对象的指针。

[in] TargetDeviceObject

指向设备堆栈中下一个较低设备对象的指针。 客户端驱动程序在上一次调用 IoAttachDeviceToDeviceStack 时接收指向该设备对象的指针。

[in] USBDClientContractVersion

客户端驱动程序支持的协定版本。 USBDClientContractVersion 必须USBD_CLIENT_CONTRACT_VERSION_602。 有关详细信息，请参阅“备注”。

[in] PoolTag

用于内存分配的池标记。

[out] USBDHandle

指示客户端驱动程序已注册到 USB 驱动程序堆栈的不透明句柄。 有关详细信息，请参阅“备注”。

返回值

例程返回 NTSTATUS 代码。 可能的值包括但不限于下表中的这些值。

返回代码 说明
STATUS_SUCCESS
 例程调用成功。
STATUS_INVALID_LEVEL
 调用方未以 IRQL 值PASSIVE_LEVEL运行。
STATUS_INVALID_PARAMETER
 调用方传递了以下无效参数值之一：
  • DeviceObject、 TargetDeviceObject 或 USBDHandle 为 NULL。
  • USBDClientContractVersion 中指定的客户端协定值无效。
  • PoolTag 为零。

注解

版本注册

Windows 8包括支持 USB 3.0 设备的新 USB 驱动程序堆栈。 新的 USB 驱动程序堆栈提供了一些新功能，例如流支持、链接的 MDL 等。 在客户端驱动程序可以使用其中任何 USB 功能之前，必须将客户端驱动程序注册到 USB 驱动程序堆栈并获取 USBD 句柄。 需要句柄才能调用使用或配置新功能的例程。 若要获取 USBD 句柄，请调用 USBD_CreateHandle。

无论设备是连接到 USB 3.0、2.0 还是 1.1 主机控制器，客户端驱动程序都必须调用 USBD_CreateHandle 。 如果设备连接到 USB 3.0 主机控制器，则 Windows 将加载 USB 3.0 驱动程序堆栈。 否则，将加载 USB 2.0 驱动程序堆栈。 在任一情况下，客户端驱动程序 都不需要 知道基础 USB 驱动程序堆栈支持的版本。 USBD_CreateHandle 评估驱动程序堆栈版本并相应地分配资源。

客户端驱动程序必须在 USBDClientContractVersion 参数中指定USBD_CLIENT_CONTRACT_VERSION_602，并遵循 最佳做法：使用 URL 中所述的一组规则。

呼叫USBD_CreateHandle

USBD_CreateHandle例程必须由 Windows 驱动程序模型 (WDM) 客户端驱动程序调用，然后驱动程序通过 URL 或 IOCTL 将任何其他请求发送到 USB 驱动程序堆栈。 通常，客户端驱动程序在其 AddDevice 例程中获取 USBD 句柄。

Windows 驱动程序框架 (WDF) 客户端驱动程序不需要调用 USBD_CreateHandle ，因为框架在设备初始化阶段代表客户端驱动程序调用此例程。 相反，客户端驱动程序可以在 WDF_USB_DEVICE_CREATE_CONFIG 结构中指定其客户端协定版本，并在调用 WdfUsbTargetDeviceCreateWithParameters 时传递它。

USBD_CreateHandle呼叫完成

如果 USBD_CreateHandle 调用成功，则会在 USBDHandle 参数中获取有效的 USBD 句柄 。 客户端驱动程序必须在客户端驱动程序对 USB 驱动程序堆栈的未来请求中使用 USBD 句柄。

如果 USBD_CreateHandle 调用失败，客户端驱动程序可能会使 AddDevice 例程失败。

客户端驱动程序使用 USBD 句柄完成后，驱动程序必须通过调用 USBD_CloseHandle 例程关闭句柄。

示例

以下示例代码演示如何通过调用 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;
    } 

    ...

}

要求

要求 值
最低受支持的客户端 Windows 8需要 WDK。 面向 Windows Vista 和更高版本的 Windows 操作系统。
目标平台 桌面
标头 usbdlib.h (包括 usbdlib.h、usb.h)
Library Usbdex.lib;Ntstrsafe.lib
IRQL PASSIVE_LEVEL

另请参阅

分配和构建 URB

最佳做法：使用 URB

USBD_CloseHandle