WdfUsbInterfaceSelectSetting 函式 (wdfusb.h)

發行項
02/27/2024

[適用於 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 目標的完成狀態值。否則，這個方法可以傳回下列其中一個值：

傳回碼	Description
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
                                      );

規格需求

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