WdfUsbTargetDeviceSelectConfig 函式 (wdfusb.h)

發行項
02/27/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

呼叫端配置的 WDF_OBJECT_ATTRIBUTES 結構的指標，其中包含架構為裝置介面所建立之新架構 USB 管道對象的屬性。對於 KMDF 驅動程式，此參數是選擇性的，而且可以WDF_NO_OBJECT_ATTRIBUTES。 UMDF 驅動程式必須將此參數設定為 NULL。

[in, out] Params

呼叫端配置 WDF_USB_DEVICE_SELECT_CONFIG_PARAMS 結構的指標，呼叫端和架構會用來指定組態參數。

傳回值

如果作業成功，WdfUsbTargetDeviceSelectConfig 會傳回 I/O 目標的完成狀態值。否則，此方法可以傳回下列其中一個值：

傳回碼	Description
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值。

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

備註

您的驅動程式可以使用 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;
}

規格需求

需求	值
目標平台	Universal
最小 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)