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_SelectInterfaceUrbAllocateAndBuildConfigurationHandle パラメーターで指定する必要があります。

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

  • InterfaceDescriptor メンバーは、選択する代替設定を持つインターフェイス記述子を含むUSB_INTERFACE_DESCRIPTOR構造体を指す必要があります。 インターフェイス記述子は、構成記述子と、関連付けられているインターフェイスとエンドポイント記述子を取得するために、前の要求で取得されました。
  • インターフェイス メンバーは 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