WdfUsbTargetDeviceSelectConfig-Funktion (wdfusb.h)

Artikel
02/29/2024

[Gilt für KMDF und UMDF]

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

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 von einem vorherigen Aufruf von WdfUsbTargetDeviceCreateWithParameters abgerufen wurde.

[in, optional] PipeAttributes

Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_OBJECT_ATTRIBUTES Struktur, die Attribute für neue Framework-USB-Pipe-Objekte enthält, die das Framework für die Schnittstellen des Geräts erstellt. Für KMDF-Treiber 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 verwenden, um Konfigurationsparameter anzugeben.

Rückgabewert

WdfUsbTargetDeviceSelectConfig gibt die Vervollständigung 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_INFO_LENGTH_MISMATCH	Das Size-Element der WDF_USB_DEVICE_SELECT_CONFIG_PARAMS Struktur, auf die Params verweist, war falsch.
STATUS_INSUFFICIENT_RESOURCES	Ein Speicherpuffer konnte nicht zugewiesen werden.
STATUS_NOT_SUPPORTED	Das Framework gibt diesen Wert zurück, wenn ein UMDF-Treiber WdfUsbTargetDeviceSelectConfig aufruft , wobei Params->Type auf einen der folgenden Werte festgelegt ist: WdfUsbTargetDeviceSelectConfigTypeDeconfig WdfUsbTargetDeviceSelectConfigTypeInterfacesDescriptor WdfUsbTargetDeviceSelectConfigTypeUrb Weitere Informationen finden Sie unter WdfUsbTargetDeviceSelectConfigType.

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

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

Hinweise

Ihr Treiber kann eine Gerätekonfiguration mithilfe einer WDF_USB_DEVICE_SELECT_CONFIG_PARAMS-Struktur auswählen, um USB-Deskriptoren, eine URB oder Handles für Framework-USB-Schnittstellenobjekte 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 die 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 WdfUsbInterfaceGetConfiguredPipe aufrufen.

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 USB-Konfiguration auszuwählen, die in der Deskriptorliste aufgeführt ist, aber Sie können mehrere Schnittstellen innerhalb 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 die 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	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfusb.h (einschließlich Wdfusb.h)
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)