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 代码。 可能的值包括但不限于下表中的这些值。
返回代码 | 说明 |
---|---|
|
例程调用成功。 |
|
调用方未以 IRQL 值PASSIVE_LEVEL运行。 |
|
调用方传递了以下无效参数值之一:
|
注解
版本注册
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 |