WdfUsbTargetDeviceSelectConfig-Funktion (wdfusb.h)

[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:

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.

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

Weitere Informationen

WDF_OBJECT_ATTRIBUTES

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_MULTIPLE_INTERFACES

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_SINGLE_INTERFACE

WdfUsbInterfaceGetConfiguredPipe

WdfUsbInterfaceGetNumConfiguredPipes

WdfUsbTargetDeviceCreateWithParameters