USBD_CreateHandle関数 (usbdlib.h)

[アーティクル]
08/07/2023

USBD_CreateHandle ルーチンは、USBD ハンドルを取得するために WDM USB クライアントドライバーによって呼び出されます。このルーチンは、基になる 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 コードを返します。次の表に示す値には、次の値が含まれますが、これらに限定されません。

リターンコード	説明
STATUS_SUCCESS	ルーチン呼び出しが成功しました。
STATUS_INVALID_LEVEL	呼び出し元が IRQL 値PASSIVE_LEVELで実行されていません。
STATUS_INVALID_PARAMETER	呼び出し元は、次のいずれかの無効なパラメーター値を渡しました。 DeviceObject、 TargetDeviceObject、または USBDHandle が NULL です。 USBDClientContractVersion で指定されたクライアントコントラクト値が無効です。 PoolTag は 0 です。

注釈

バージョン登録

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を指定し、「ベストプラクティス: URB の使用」で説明されている一連の規則に従う必要があります。

USBD_CreateHandleの呼び出し

ドライバーが USB ドライバースタックに URL または IOCTL を介して他の要求を送信する前に、windows ドライバーモデル (WDM) クライアントドライバーによって、 USBD_CreateHandle ルーチンを呼び出す必要があります。通常、クライアントドライバーは AddDevice ルーチンで USBD ハンドルを取得します。

Windows Driver Frameworks (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 オペレーティングシステムを対象としています。
対象プラットフォーム	デスクトップ
Header	usbdlib.h (usbdlib.h、usb.h を含む)
Library	Usbdex.lib;Ntstrsafe.lib
IRQL	PASSIVE_LEVEL

こちらもご覧ください

URB の割り当てと構築

ベストプラクティス:URB の使用

USBD_CloseHandle

次の方法で共有