次の方法で共有

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 の使用を完了したときに URB を解放する必要があります。

戻り値

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

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

備考

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

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

  • InterfaceDescriptor メンバーは、選択する代替設定を持つインターフェイス記述子を含む USB_INTERFACE_DESCRIPTOR 構造体を指す必要があります。 インターフェイス記述子は、構成記述子と、関連付けられているインターフェイスとエンドポイント記述子を取得する前の要求で取得されました。
  • インターフェイス メンバーは NULL である必要があります。
USBD_SelectInterfaceUrbAllocateAndBuild は、URB 構造体を割り当て、指定されたインターフェイス設定とエンドポイントに関する情報を入力します。 ルーチンは、USBD_INTERFACE_INFORMATION 構造体も割り当てます。 構造体メンバー (パイプ情報を除く) は、指定されたインターフェイス記述子に基づいて入力されます。 USBD_SelectInterfaceUrbAllocateAndBuild、USBD_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 オペレーティング システムを対象としています。
ターゲット プラットフォーム の デスクトップ
ヘッダー usbdlib.h
ライブラリ Usbdex.lib
IRQL DISPATCH_LEVEL

関連項目

USBD_CreateHandle

USBD_SelectConfigUrbAllocateAndBuild