WdfUsbTargetDeviceSelectConfig-Funktion (wdfusb.h)

Artikel
02/07/2025

[Gilt für KMDF und UMDF]

Die WdfUsbTargetDeviceSelectConfig- Methode wählt eine USB-Konfiguration für ein Gerät aus, oder das Gerät wird deaktiviert.

Syntax

NTSTATUS WdfUsbTargetDeviceSelectConfig(
  [in]           WDFUSBDEVICE                         UsbDevice,
  [in, optional] PWDF_OBJECT_ATTRIBUTES               PipeAttributes,
  [in, out]      PWDF_USB_DEVICE_SELECT_CONFIG_PARAMS Params
);

Parameter

[in] UsbDevice

Ein Handle für ein USB-Geräteobjekt, das aus einem vorherigen Aufruf von WdfUsbTargetDeviceCreateWithParametersabgerufen wurde.

[in, optional] PipeAttributes

Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_OBJECT_ATTRIBUTES-Struktur, die Attribute für neue Framework-USB-Pipeobjekte enthält, die das Framework für die Geräteschnittstellen erstellt. Bei KMDF-Treibern ist dieser Parameter optional und kann WDF_NO_OBJECT_ATTRIBUTES werden. UMDF-Treiber müssen diesen Parameter auf NULL festlegen.

[in, out] Params

Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_USB_DEVICE_SELECT_CONFIG_PARAMS Struktur, die der Aufrufer und das Framework zum Angeben von Konfigurationsparametern verwenden.

Rückgabewert

WdfUsbTargetDeviceSelectConfig gibt den Fertigstellungsstatuswert des E/A-Ziels 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_INFO_LENGTH_MISMATCH	Das Size Element der WDF_USB_DEVICE_SELECT_CONFIG_PARAMS Struktur, auf das Params verweist, war falsch.
STATUS_INSUFFICIENT_RESOURCES	Ein Speicherpuffer konnte nicht zugeordnet werden.
STATUS_NOT_SUPPORTED	Das Framework gibt diesen Wert zurück, wenn ein UMDF-Treiber WdfUsbTargetDeviceSelectConfig mit Params->Type auf einen der folgenden Werte festgelegt wird: WdfUsbTargetDeviceSelectConfigTypeDeconfigDeconfig WdfUsbTargetDeviceSelectConfigTypeInterfacesDescriptor WdfUsbTargetDeviceSelectConfigTypeUrb Weitere Informationen finden Sie unter WdfUsbTargetDeviceSelectConfigType.

Diese Methode kann auch andere NTSTATUS-Wertezurückgeben.

Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.

Bemerkungen

Ihr Treiber kann eine Gerätekonfiguration mithilfe einer WDF_USB_DEVICE_SELECT_CONFIG_PARAMS Struktur auswählen, um USB-Deskriptoren, urB oder Handles für das Framework von USB-Schnittstellenobjekten anzugeben.

Das Framework erstellt ein Framework-USB-Pipeobjekt für jede Pipe, die jeder Schnittstelle in der Konfiguration zugeordnet ist, nachdem alle Pipeobjekte gelöscht wurden, die das Framework möglicherweise zuvor für die Konfiguration erstellt hat. Das Framework verwendet alternative Einstellung null für jede Schnittstelle, es sei denn, der Treiber gibt eine andere alternative Einstellung an.

Um Informationen zu den Pipeobjekten einer Schnittstelle abzurufen, kann der Treiber WdfUsbInterfaceGetNumConfiguredPipes und WdfUsbInterfaceGetConfiguredPipeaufrufen.

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

Vorsicht

Sie können WdfUsbTargetDeviceSelectConfig- verwenden, um nur die erste in der Beschreibungsliste aufgeführte USB-Konfiguration auszuwählen. Sie können jedoch mehrere Schnittstellen in dieser einzelnen Konfiguration auswählen.

Beispiele

Im folgenden Codebeispiel wird eine Konfiguration mit einer einzelnen, angegebenen Schnittstelle ausgewählt.

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

Im folgenden Codebeispiel wird eine Konfiguration mit mehreren Schnittstellen ausgewählt, wobei alternative Einstellung Null für alle Schnittstellen verwendet wird. Dieses Beispiel gilt nur für KMDF-Treiber.

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

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Minimale KMDF-Version	1.0
Mindest-UMDF-Version	2.0
Header-	wdfusb.h (include Wdfusb.h)
Library	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)