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运行。 |
|
调用方传递了以下无效参数值之一:
|
无论设备是连接到 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,并遵循 最佳做法中所述的规则集:使用 URBs。
在驱动程序通过 URL 或 IOCTL 向 USB 驱动程序堆栈发送任何其他请求之前,Windows 驱动程序模型(WDM)客户端驱动程序必须调用 USBD_CreateHandle 例程。 通常,客户端驱动程序在其 AddDevice 例程中获取 USBD 句柄。不需要 Windows 驱动程序框架(WDF)客户端驱动程序来调用 USBD_CreateHandle,因为框架在设备初始化阶段代表客户端驱动程序调用此例程。 相反,客户端驱动程序可以在 WDF_USB_DEVICE_CREATE_CONFIG 结构中指定其客户端协定版本,并在调用 WdfUsbTargetDeviceCreateWithParameters中传递它。
如果 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) |
库 | Usbdex.lib;Ntstrsafe.lib |
IRQL | PASSIVE_LEVEL |