WdfUsbTargetDeviceSelectConfig 函式（wdfusb.h）

發行項
02/07/2025

[適用於 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

呼叫端配置的 WDF_OBJECT_ATTRIBUTES 結構的指標，其中包含架構為裝置介面所建立之新架構 USB 管道對象的屬性。對於 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 結構大小成員不正確。
STATUS_INSUFFICIENT_RESOURCES	無法配置記憶體緩衝區。
STATUS_NOT_SUPPORTED	如果 UMDF 驅動程式呼叫 WdfUsbTargetDeviceSelectConfig WdfUsbTargetDeviceSelectConfig，且參數->Type 設為下列任一項，架構會傳回此值： WdfUsbTargetDeviceSelectConfigTypeDeconfig WdfUsbTargetDeviceSelectConfigTypeInterfacesDescriptor WdfUsbTargetDeviceSelectConfigTypeUrb 如需詳細資訊，請參閱 WdfUsbTargetDeviceSelectConfigType。

此方法也可能傳回其他NTSTATUS 值。

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

言論

您的驅動程式可以使用 WDF_USB_DEVICE_SELECT_CONFIG_PARAMS 結構來指定 USB 描述元、URB 或架構 USB 介面物件的句柄來選取裝置組態。

架構會針對組態中每個介面相關聯的每個管道建立架構 USB 管道對象，然後刪除架構先前可能為組態建立的任何管道物件。架構會針對每個介面使用替代設定零，除非驅動程式指定不同的替代設定。

若要取得介面管道對象的相關信息，驅動程式可以呼叫 WdfUsbInterfaceGetNumConfiguredPipes 和 WdfUsbInterfaceGetConfiguredPipe。

如需 WdfUsbTargetDeviceSelectConfig 方法和 USB I/O 目標的詳細資訊，請參閱 USB I/O 目標。

注意

您可以使用 WdfUsbTargetDeviceSelectConfig 只選取描述元清單中所列的第一個 USB 組態，但您可以在此單一設定中選取多個介面。

例子

下列程式代碼範例會選取具有單一指定介面的組態。

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
                                        );

下列程式代碼範例會選取具有多個介面的組態，並在所有介面上使用替代設定零。此範例僅適用於 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
標頭	wdfusb.h （包括 Wdfusb.h）
連結庫	Wdf01000.sys （KMDF）：WUDFx02000.dll （UMDF）
IRQL	PASSIVE_LEVEL
DDI 合規性規則	DriverCreate（kmdf），KmdfIrql（kmdf），KmdfIrql2（kmdf），KmdfIrqlExplicit（kmdf），UsbKmdfIrql（kmdf），UsbKmdfIrql2（kmdf），UsbKmdfIrqlExplicit（kmdf）