WdfUsbInterfaceSelectSetting 関数 (wdfusb.h)

[アーティクル]
02/27/2024

[KMDF と UMDF に適用]

WdfUsbInterfaceSelectSetting メソッドは、指定された USB インターフェイスの指定した代替設定を選択します。

構文

NTSTATUS WdfUsbInterfaceSelectSetting(
  [in]           WDFUSBINTERFACE                          UsbInterface,
  [in, optional] PWDF_OBJECT_ATTRIBUTES                   PipesAttributes,
  [in]           PWDF_USB_INTERFACE_SELECT_SETTING_PARAMS Params
);

パラメーター

[in] UsbInterface

WdfUsbTargetDeviceGetInterface を呼び出すことによって取得された USB インターフェイスオブジェクトへのハンドル。

[in, optional] PipesAttributes

フレームワークがインターフェイス用に作成するパイプオブジェクトのオブジェクト属性を指定する WDF_OBJECT_ATTRIBUTES 構造体へのポインター。このパラメーターは省略可能であり、WDF_NO_OBJECT_ATTRIBUTESできます。

[in] Params

インターフェイス選択パラメーターを含む呼び出し元から提供された WDF_USB_INTERFACE_SELECT_SETTING_PARAMS 構造体へのポインター。

戻り値

操作が成功した場合、WdfUsbInterfaceSelectSetting は I/O ターゲットの完了状態値を返します。それ以外の場合、このメソッドは次のいずれかの値を返すことができます。

リターンコード	説明
STATUS_INVALID_PARAMETER	無効なパラメーターが検出されました。
STATUS_INSUFFICIENT_RESOURCES	新しいパイプオブジェクトを作成するためのメモリが不足していました。

WdfUsbInterfaceSelectSetting メソッドが返す可能性があるその他の戻り値の一覧については、「フレームワークオブジェクト作成エラー」を参照してください。

このメソッドは、他の NTSTATUS 値を返す場合もあります。

ドライバーが無効なオブジェクトハンドルを提供すると、バグチェックが発生します。

注釈

ドライバーが WdfUsbTargetDeviceSelectConfig を呼び出して構成を選択した後、ドライバーは WdfUsbInterfaceSelectSetting を呼び出して、デバイスのいずれかのインターフェイスの代替設定を選択できます。

ドライバーは、USB インターフェイス記述子または URB を指定するか、インターフェイスの代替設定を指定するだけで、インターフェイスの代替設定を選択できます。いずれの場合も、ドライバーはインターフェイスオブジェクトへのハンドルを提供する必要があります。

ドライバーが代替設定を提供するだけの場合、フレームワークはインターフェイスオブジェクトを使用して、設定が属するインターフェイスを決定します。

ドライバーでインターフェイス記述子または URB が指定されている場合、フレームワークは記述子または URB で指定されたインターフェイスを使用します。

フレームワークは、フレームワークがインターフェイス用に以前に作成したパイプオブジェクトを削除した後、インターフェイスに関連付けられている各パイプに対してフレームワーク USB パイプオブジェクトを作成します。インターフェイスのパイプオブジェクトに関する情報を取得するために、ドライバーは WdfUsbInterfaceGetNumConfiguredPipes と WdfUsbInterfaceGetConfiguredPipe を呼び出すことができます。

WdfUsbInterfaceSelectSetting メソッドと USB I/O ターゲットの詳細については、「USB I/O ターゲット」を参照してください。

例

次のコード例では、フレームワークによって作成されるパイプオブジェクトの属性を使用して、 WDF_OBJECT_ATTRIBUTES 構造体を初期化します。次に、代替設定 1 を指定するために、WDF_USB_INTERFACE_SELECT_SETTING_PARAMS 構造体を初期化します。最後に、この例では WdfUsbInterfaceSelectSetting を呼び出して代替設定を選択し、インターフェイスのパイプのパイプオブジェクトを作成します。

WDF_OBJECT_ATTRIBUTES  pipesAttributes;
WDF_USB_INTERFACE_SELECT_SETTING_PARAMS  selectSettingParams;
NTSTATUS  Status;

WDF_OBJECT_ATTRIBUTES_INIT(&pipesAttributes);
WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE(
                                       &pipesAttributes,
                                       MY_PIPE_CONTEXT
                                       );

WDF_USB_INTERFACE_SELECT_SETTING_PARAMS_INIT_SETTING(
                                      &selectSettingParams,
                                      1
                                      );

Status = WdfUsbInterfaceSelectSetting(
                                      UsbInterface,
                                      &pipesAttributes,
                                      &selectSettingParams
                                      );

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 KMDF バージョン	1.0
最小 UMDF バージョン	2.0
Header	wdfusb.h (Wdfusb.h を含む)
Library	Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI コンプライアンス規則	DriverCreate(kmdf)、 KmdfIrql(kmdf)、 KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)、 UsbKmdfIrql(kmdf)、 UsbKmdfIrql2(kmdf)、UsbKmdfIrqlExplicit(kmdf)