USBD_CreateHandle関数 (usbdlib.h)

  • [アーティクル]

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