USBD_SelectInterfaceUrbAllocateAndBuild関数 (usbdlib.h)

  • [アーティクル]

USBD_SelectInterfaceUrbAllocateAndBuild ルーチンは、要求がインターフェイスを選択したり、別の設定を変更したりするために必要な URB 構造体を割り当てて書式設定します。

構文

NTSTATUS USBD_SelectInterfaceUrbAllocateAndBuild(
  [in]  USBD_HANDLE                USBDHandle,
  [in]  USBD_CONFIGURATION_HANDLE  ConfigurationHandle,
        PUSBD_INTERFACE_LIST_ENTRY InterfaceListEntry,
  [out] PURB                       *Urb
);

パラメーター

[in] USBDHandle

USBD_CreateHandle ルーチンの以前の呼び出しでクライアント ドライバーによって取得される USBD ハンドル。

[in] ConfigurationHandle

ドライバー スタックが選択構成要求を完了した後、URB 構造体の UrbSelectConfiguration.ConfigurationHandle メンバーの USB ドライバー スタックによって返されるハンドル。

InterfaceListEntry

呼び出し元によって割り当てられた USBD_INTERFACE_LIST_ENTRY 構造体へのポインター。 詳細については、「解説」を参照してください。

[out] Urb

USBD_SelectInterfaceUrbAllocateAndBuildによって割り当てられた URB を受け取る URB 構造体へのポインター。 クライアント ドライバーは、ドライバーが USBD_UrbFreeを呼び出して URB の使用を完了したときに解放する必要があります。

戻り値

ルーチンは NTSTATUS コードを返します。 使用できる値には、次の表に示す状態コードが含まれますが、これらに限定されません。

リターン コード 説明
STATUS_SUCCESS
 ルーチン呼び出しが成功しました。
STATUS_INVALID_PARAMETER
 呼び出し元は、いずれかのパラメーターで NULL を渡しました。
STATUS_INSUFFICIENT_RESOURCES
 呼び出しを完了するために使用できるメモリが不足しています。

注釈

クライアント ドライバーは、デバイスで構成を選択した後 、USBD_SelectInterfaceUrbAllocateAndBuild ルーチンを呼び出す必要があります。 選択構成要求が完了すると、クライアント ドライバーは URB の UrbSelectConfiguration.ConfigurationHandle メンバーで構成ハンドルを受け取ります。 そのハンドルは、USBD_SelectInterfaceUrbAllocateAndBuildの ConfigurationHandle パラメーターで指定 する必要があります。

クライアント ドライバーは 、選択 した構成で、インターフェイスの代替設定を変更する選択インターフェイス要求の URB を割り当ててビルドするUSBD_SelectInterfaceUrbAllocateAndBuildを呼び出します。 USBD_SelectInterfaceUrbAllocateAndBuildの呼び出しでは、クライアント ドライバーは、USBD_INTERFACE_LIST_ENTRY構造体へのポインターを割り当てて提供する必要があります。 クライアント ドライバーは、構造体のメンバーを次のように設定する必要があります。

  • InterfaceDescriptor メンバーは、選択する代替設定を持つインターフェイス記述子を含むUSB_INTERFACE_DESCRIPTOR構造体を指す必要があります。 インターフェイス記述子は、構成記述子と、関連付けられているインターフェイス記述子とエンドポイント記述子を取得する前の要求で取得されました。
  • Interface メンバーは NULL である必要があります。
USBD_SelectInterfaceUrbAllocateAndBuildURB 構造体を割り当て、指定したインターフェイス設定とエンドポイントに関する情報を入力します。 ルーチンでは、 USBD_INTERFACE_INFORMATION 構造体も割り当てられます。 構造体メンバー (パイプ情報を除く) は、指定されたインターフェイス記述子に基づいて入力されます。 USBD_SelectInterfaceUrbAllocateAndBuildUSBD_INTERFACE_LIST_ENTRYのInterface メンバーを URB のUSBD_INTERFACE_INFORMATIONのアドレスに設定します。 クライアント ドライバーは、この URB を USB ドライバー スタックに送信して、インターフェイスの代替設定を選択できます。

クライアント ドライバーは、1 つの選択インターフェイス要求で複数のインターフェイスの代替設定を変更することはできません。 各要求は、1 つのインターフェイスのみを対象としています。

インターフェイスの選択要求が完了すると、USB ドライバー スタックは、選択した代替設定で定義されているエンドポイント用に開かれたパイプに関する情報を USBD_INTERFACE_INFORMATION に設定します。 クライアント ドライバーは、USBD_INTERFACE_INFORMATION の Pipes メンバーが指す配列を調べることで、これらのパイプ ハンドルを取得 し、将来のデータ転送要求のハンドルを格納できます。

クライアント ドライバーは、同じ代替設定の別の選択インターフェイス要求に対してのみ、USBD_SelectInterfaceUrbAllocateAndBuildによって割り当てられた URB を再利用できます。 クライアント ドライバーは、他の種類の要求に対して URB を再利用したり、別の代替設定に対して別の選択インターフェイス要求を再利用 したりしてはなりません 。 特定のシナリオでは、新しい URB を割り当てる代わりに、既存の URB を再利用することをお勧めします。 2 つの帯域幅要件に対して定義された 2 つの代替設定を持つインターフェイスを持つ USB オーディオ デバイスについて考えてみましょう。 0 を設定すると、帯域幅がゼロになります。設定 1 は、一定の帯域幅を使用するように定義されます。 クライアント ドライバーは、デバイスが使用中かどうかに応じて、2 つの設定を頻繁に切り替える必要があります。 このシナリオを実装するために、クライアント ドライバーは、設定ごとに 1 つずつ、選択インターフェイス要求に 2 つの URB を割り当てることができます。 クライアント ドライバーは、デバイスに送信するサウンドがある場合に設定 1 を選択する選択インターフェイス要求に URB を使用 (および再利用) できます。 サウンドがないときに帯域幅を節約するために、クライアント ドライバーは他の URB を使用 (および再利用) して設定 0 に切り替えることができます。 この実装では、ドライバーが設定を変更する必要があるたびに、クライアント ドライバーがこれらの選択インターフェイス要求ごとに URB を割り当てないようにします。

要件

要件 値
サポートされている最小のクライアント Windows 8には WDK が必要です。 Windows Vista 以降のバージョンの Windows オペレーティング システムを対象としています。
対象プラットフォーム デスクトップ
Header usbdlib.h
Library Usbdex.lib
IRQL DISPATCH_LEVEL

こちらもご覧ください

USBD_CreateHandle

USBD_SelectConfigUrbAllocateAndBuild