USBD_CreateHandle函式 (usbdlib.h)

發行項
02/27/2024

USBD_CreateHandle例程是由 WDM USB 用戶端驅動程式呼叫，以取得 USBD 句柄。例程會向基礎 USB 驅動程式堆疊註冊客戶端驅動程式。

Windows Driver Framework (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程式代碼。可能的值包括但不限於下表中的這些值。

傳回碼	Description
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)
程式庫	Usbdex.lib;Ntstrsafe.lib
IRQL	PASSIVE_LEVEL

另請參閱

配置和建置URL

最佳做法：使用 URB

USBD_CloseHandle

共用方式為