WdfUsbTargetDeviceSelectConfig 関数 (wdfusb.h)

[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 ターゲットの完了状態値を返します。 それ以外の場合、このメソッドは次のいずれかの値を返すことができます。

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

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

注釈

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

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

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

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

例

次のコード例では、指定された 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;
}

要件

こちらもご覧ください

WDF_OBJECT_ATTRIBUTES

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_MULTIPLE_INTERFACES

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_SINGLE_INTERFACE

WdfUsbInterfaceGetConfiguredPipe

WdfUsbInterfaceGetNumConfiguredPipes

WdfUsbTargetDeviceCreateWithParameters