WdfUsbInterfaceSelectSetting 函式（wdfusb.h）

發行項
02/07/2025

[適用於 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 方法可能會傳回的其他傳回值清單，請參閱 Framework 物件建立錯誤。

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

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

言論

驅動程式呼叫 WdfUsbTargetDeviceSelectConfig 以選取組態之後，驅動程式可以呼叫 WdfUsbInterfaceSelectSetting 來選取其中一個裝置介面的替代設定。

您的驅動程式可以藉由指定USB介面描述元或 URB來選取介面的替代設定，或只提供介面的替代設定。在所有情況下，驅動程式都必須提供介面物件的句柄。

如果您的驅動程式只是提供替代設定，架構會使用介面對象來判斷設定所屬的介面。

如果您的驅動程式指定介面描述元或URB，架構會使用描述元或URB中指定的介面。

架構會在刪除架構之前為介面建立的任何管道對象之後，為每個與介面相關聯的管道建立架構 USB 管道物件。若要取得介面管道對象的相關信息，驅動程式可以呼叫 WdfUsbInterfaceGetNumConfiguredPipes 和 WdfUsbInterfaceGetConfiguredPipe。

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

例子

下列程式代碼範例會使用架構將建立之管道對象的屬性，初始化 WDF_OBJECT_ATTRIBUTES 結構。然後，此範例會初始化 WDF_USB_INTERFACE_SELECT_SETTING_PARAMS 結構，以指定替代設定 1。最後，此範例會呼叫 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
標頭	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）