次の方法で共有

USBD_CreateHandle関数 (usbdlib.h)

  • [アーティクル]

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 コードを返します。 使用可能な値には、次の表に示す値が含まれますが、これらに限定されません。

リターン コード 形容
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

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

Windows Driver Frameworks (WDF) クライアント ドライバーは、デバイスの初期化フェーズ中にクライアント ドライバーの代わりにこのルーチンを呼び出すので、USBD_CreateHandle を呼び出す必要はありません。 代わりに、クライアント ドライバーは、WDF_USB_DEVICE_CREATE_CONFIG 構造体でクライアント コントラクトのバージョンを指定し、WdfUsbTargetDeviceCreateWithParametersへの呼び出しで渡すことができます。

USBD_CreateHandle 呼び出しの完了

USBD_CreateHandle 呼び出しが成功した場合、有効な USBD ハンドル は、USBDHandle パラメーターで取得されます。 クライアント ドライバーは、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

関連項目

URB の割り当てと構築

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

USBD_CloseHandle