WdfUsbTargetDeviceSelectConfig 関数 (wdfusb.h)

[アーティクル]
03/05/2024

[KMDF と UMDF に適用]

WdfUsbTargetDeviceSelectConfig メソッドは、デバイスの USB 構成を選択するか、デバイスを構成解除します。

構文

NTSTATUS WdfUsbTargetDeviceSelectConfig(
  [in]           WDFUSBDEVICE                         UsbDevice,
  [in, optional] PWDF_OBJECT_ATTRIBUTES               PipeAttributes,
  [in, out]      PWDF_USB_DEVICE_SELECT_CONFIG_PARAMS Params
);

パラメーター

[in] UsbDevice

WdfUsbTargetDeviceCreateWithParameters の以前の呼び出しから取得された USB デバイスオブジェクトへのハンドル。

[in, optional] PipeAttributes

デバイスのインターフェイス用にフレームワークによって作成される新しいフレームワーク USB パイプオブジェクトの属性を含む、呼び出し元によって割り当てられた WDF_OBJECT_ATTRIBUTES 構造体へのポインター。 KMDF ドライバーの場合、このパラメーターは省略可能であり、WDF_NO_OBJECT_ATTRIBUTESできます。 UMDF ドライバーでは、このパラメーターを NULL に設定する必要があります。

[in, out] Params

呼び出し元とフレームワークが構成パラメーターを指定するために使用する呼び出し元によって割り当てられた WDF_USB_DEVICE_SELECT_CONFIG_PARAMS 構造体へのポインター。

戻り値

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

リターンコード	説明
STATUS_INVALID_PARAMETER	無効なパラメーターが検出されました。
STATUS_INFO_LENGTH_MISMATCH	Params が指すWDF_USB_DEVICE_SELECT_CONFIG_PARAMS構造体の Size メンバーが正しくありません。
STATUS_INSUFFICIENT_RESOURCES	メモリバッファーを割り当てませんでした。
STATUS_NOT_SUPPORTED	UMDF ドライバーで WdfUsbTargetDeviceSelectConfig が呼び出され、 Params->Type が次のいずれかに設定されている場合、フレームワークはこの値を返します。 WdfUsbTargetDeviceSelectConfigTypeDeconfig WdfUsbTargetDeviceSelectConfigTypeInterfacesDescriptor WdfUsbTargetDeviceSelectConfigTypeUrb 詳細については、「 WdfUsbTargetDeviceSelectConfigType」を参照してください。

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

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

注釈

ドライバーは、USB 記述子、URB、またはフレームワーク USB インターフェイスオブジェクトへのハンドルを指定する WDF_USB_DEVICE_SELECT_CONFIG_PARAMS 構造体を使用して、デバイス構成を選択できます。

フレームワークは、構成用にフレームワークが以前に作成したパイプオブジェクトを削除した後、構成内の各インターフェイスに関連付けられている各パイプに対してフレームワーク USB パイプオブジェクトを作成します。フレームワークでは、ドライバーが別の代替設定を指定しない限り、インターフェイスごとに代替設定 0 を使用します。

インターフェイスのパイプオブジェクトに関する情報を取得するために、ドライバーは WdfUsbInterfaceGetNumConfiguredPipes と WdfUsbInterfaceGetConfiguredPipe を呼び出すことができます。

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

注意

WdfUsbTargetDeviceSelectConfig を使用すると、記述子リストに一覧表示されている最初の USB 構成のみを選択できますが、この 1 つの構成内で複数のインターフェイスを選択できます。

例

次のコード例では、指定された 1 つのインターフェイスを持つ構成を選択します。

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS  configParams;
NTSTATUS  status;

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_SINGLE_INTERFACE(&configParams);

status = WdfUsbTargetDeviceSelectConfig(
                                        UsbDevice,
                                        WDF_NO_OBJECT_ATTRIBUTES,
                                        &configParams
                                        );

次のコード例では、すべてのインターフェイスで代替設定 0 を使用して、複数のインターフェイスを持つ構成を選択します。この例は、KMDF ドライバーにのみ適用されます。

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS  configParams;
PWDF_USB_INTERFACE_SETTING_PAIR settingPairs;
UCHAR numInterfaces;
NTSTATUS  status;

numInterfaces = WdfUsbTargetDeviceGetNumInterfaces(UsbDevice);

settingPairs = ExAllocatePoolWithTag(
    PagedPool,
    sizeof(WDF_USB_INTERFACE_SETTING_PAIR) * numInterfaces,
    MY_DRIVER_TAG
);

if (settingPairs == NULL){
    return STATUS_INSUFFICIENT_RESOURCES;
}

for (interfaceIndex = 0; interfaceIndex < numInterfaces; interfaceIndex++) {
        
    settingPairs[interfaceIndex].UsbInterface = 
                                    WdfUsbTargetDeviceGetInterface(
                                        UsbDevice,
                                        interfaceIndex);

    // Select alternate setting zero on all interfaces.
       
    settingPairs[interfaceIndex].SettingIndex = 0;
}

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_MULTIPLE_INTERFACES(
    &configParams,
    numInterfaces,
    settingPairs
);

status = WdfUsbTargetDeviceSelectConfig(
    UsbDevice,
    NULL,
    &configParams
);

if (!NT_SUCCESS(status)) {
    ExFreePoolWithTag(
        settingPairs,
        MY_DRIVER_TAG
    );
    return status;
}

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 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)