WdfUsbInterfaceSelectSetting-Funktion (wdfusb.h)

Artikel
02/27/2024

[Gilt für KMDF und UMDF]

Die WdfUsbInterfaceSelectSetting-Methode wählt eine angegebene alternative Einstellung für eine angegebene USB-Schnittstelle aus.

Syntax

NTSTATUS WdfUsbInterfaceSelectSetting(
  [in]           WDFUSBINTERFACE                          UsbInterface,
  [in, optional] PWDF_OBJECT_ATTRIBUTES                   PipesAttributes,
  [in]           PWDF_USB_INTERFACE_SELECT_SETTING_PARAMS Params
);

Parameter

[in] UsbInterface

Ein Handle für ein USB-Schnittstellenobjekt, das durch Aufrufen von WdfUsbTargetDeviceGetInterface abgerufen wurde.

[in, optional] PipesAttributes

Ein Zeiger auf eine WDF_OBJECT_ATTRIBUTES-Struktur , die Objektattribute für Pipeobjekte angibt, die das Framework für die Schnittstelle erstellt. Dieser Parameter ist optional und kann WDF_NO_OBJECT_ATTRIBUTES werden.

[in] Params

Ein Zeiger auf eine vom Aufrufer bereitgestellte WDF_USB_INTERFACE_SELECT_SETTING_PARAMS-Struktur , die Schnittstellenauswahlparameter enthält.

Rückgabewert

WdfUsbInterfaceSelectSetting gibt den Abschluss des E/A-Ziels status Wert zurück, wenn der Vorgang erfolgreich ist. Andernfalls kann diese Methode einen der folgenden Werte zurückgeben:

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Ein ungültiger Parameter wurde erkannt.
STATUS_INSUFFICIENT_RESOURCES	Es war nicht genügend Arbeitsspeicher vorhanden, um ein neues Pipeobjekt zu erstellen.

Eine Liste mit anderen Rückgabewerten, die von der WdfUsbInterfaceSelectSetting-Methode möglicherweise zurückgegeben werden, finden Sie unter Fehler bei der Erstellung von Frameworkobjekten.

Diese Methode kann auch andere NTSTATUS-Werte zurückgeben.

Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.

Hinweise

Nachdem Ihr Treiber WdfUsbTargetDeviceSelectConfig aufgerufen hat , um eine Konfiguration auszuwählen, kann der Treiber WdfUsbInterfaceSelectSetting aufrufen, um eine alternative Einstellung für eine der Schnittstellen des Geräts auszuwählen.

Ihr Treiber kann die alternative Einstellung einer Schnittstelle auswählen, indem er einen USB-Schnittstellendeskriptor oder eine URB angibt oder einfach eine alternative Einstellung für die Schnittstelle bereitstellt. In allen Fällen muss der Treiber ein Handle für ein Schnittstellenobjekt bereitstellen.

Wenn Ihr Treiber nur eine alternative Einstellung bereitstellt, verwendet das Framework das Schnittstellenobjekt, um die Schnittstelle zu bestimmen, zu der die Einstellung gehört.

Wenn Ihr Treiber einen Schnittstellendeskriptor oder eine URB angibt, verwendet das Framework die Schnittstelle, die im Deskriptor oder URB angegeben ist.

Das Framework erstellt ein Framework-USB-Pipeobjekt für jede Pipe, die der Schnittstelle zugeordnet ist, nachdem alle Pipeobjekte gelöscht wurden, die das Framework möglicherweise zuvor für die Schnittstelle erstellt hat. Um Informationen zu den Pipeobjekten einer Schnittstelle zu erhalten, kann Ihr Treiber WdfUsbInterfaceGetNumConfiguredPipes und WdfUsbInterfaceGetConfiguredPipe aufrufen.

Weitere Informationen zur WdfUsbInterfaceSelectSetting-Methode und USB-E/A-Zielen finden Sie unter USB-E/A-Ziele.

Beispiele

Im folgenden Codebeispiel wird eine WDF_OBJECT_ATTRIBUTES-Struktur mit Attributen für die Pipeobjekte initialisiert, die vom Framework erstellt werden. Anschließend initialisiert das Beispiel eine WDF_USB_INTERFACE_SELECT_SETTING_PARAMS-Struktur , um die alternative Einstellung 1 anzugeben. Schließlich ruft das Beispiel WdfUsbInterfaceSelectSetting auf, um die alternative Einstellung auszuwählen und Pipeobjekte für die Pipes der Schnittstelle zu erstellen.

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

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfusb.h (wdfusb.h einschließen)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)