WdfUsbTargetDeviceRetrieveConfigDescriptor-Funktion (wdfusb.h)

Artikel
08/08/2023

[Gilt für KMDF und UMDF]

Die WdfUsbTargetDeviceRetrieveConfigDescriptor-Methode ruft den USB-Konfigurationsdeskriptor für das USB-Gerät ab, das einem angegebenen FRAMEWORK-USB-Geräteobjekt zugeordnet ist.

Syntax

NTSTATUS WdfUsbTargetDeviceRetrieveConfigDescriptor(
  [in]      WDFUSBDEVICE UsbDevice,
  [out]     PVOID        ConfigDescriptor,
  [in, out] PUSHORT      ConfigDescriptorLength
);

Parameter

[in] UsbDevice

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

[out] ConfigDescriptor

Ein Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der eine USB_CONFIGURATION_DESCRIPTOR-Struktur empfängt, gefolgt von einer oder mehreren USB_INTERFACE_DESCRIPTOR - und USB_ENDPOINT_DESCRIPTOR-Strukturen . Dieser Parameter ist optional und kann NULL sein. In diesem Fall gibt WdfUsbTargetDeviceRetrieveConfigDescriptor die erforderliche Pufferlänge zurück. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in, out] ConfigDescriptorLength

Ein Zeiger auf eine Position, die die Länge des Puffers angibt, auf den ConfigDescriptor verweist. Wenn der für ConfigDescriptor angegebene Zeiger NULL ist, gibt WdfUsbTargetDeviceRetrieveConfigDescriptor die erforderliche Pufferlänge an der Position zurück, auf die von ConfigDescriptorLength verwiesen wird.

Rückgabewert

WdfUsbTargetDeviceRetrieveConfigDescriptor gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls kann diese Methode einen der folgenden Werte zurückgeben:

Rückgabecode	Beschreibung
STATUS_INVALID_DEVICE_STATE	Ein Konfigurationsdeskriptor war für das angegebene Ziel nicht verfügbar.
STATUS_INVALID_PARAMETER	Ein ungültiger Parameter wurde erkannt.
STATUS_BUFFER_TOO_SMALL	Die angegebene Puffergröße war zu klein für die Daten, oder der Aufrufer hat NULL für den ConfigDescriptor-Parameter angegeben.

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

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

Hinweise

Die WdfUsbTargetDeviceRetrieveConfigDescriptor-Methode ruft alle Konfigurationsinformationen des angegebenen USB-Geräts ab (also den Konfigurationsdeskriptor sowie alle möglicherweise vorhandenen Schnittstellen- oder Endpunktdeskriptoren). Informationen zum Format dieser Informationen finden Sie in der USB-Spezifikation.

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.

Treiber sollten WdfUsbTargetDeviceRetrieveConfigDescriptor wie folgt zweimal aufrufen:

Legen Sie den ConfigDescriptor-Zeiger auf NULL fest, damit WdfUsbTargetDeviceRetrieveConfigDescriptor die erforderliche Puffergröße in der Adresse zurückgibt, auf die ConfigDescriptorLength verweist.
Weisen Sie Pufferspeicherplatz zu, um die Konfigurationsinformationen zu enthalten. Beispielsweise kann ein Treiber ExAllocatePoolWithTag aufrufen, um einen Puffer zuzuweisen, oder er ruft WdfMemoryCreate auf , um ein Framework-Speicherobjekt zu erstellen.
Rufen Sie WdfUsbTargetDeviceRetrieveConfigDescriptor erneut auf, und übergeben Sie einen Zeiger auf den neuen Puffer und die Größe des Puffers.

Nachdem der zweite Aufruf von WdfUsbTargetDeviceRetrieveConfigDescriptor zurückgegeben wurde, enthält der Puffer, auf den von ConfigDescriptor verwiesen wird, eine USB_CONFIGURATION_DESCRIPTOR-Struktur , gefolgt von mindestens einer USB_INTERFACE_DESCRIPTOR - und USB_ENDPOINT_DESCRIPTOR-Struktur . Diese letztgenannten Strukturen sind in der Reihenfolge angeordnet, die in der USB-Spezifikation beschrieben ist.

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

Beispiele

Im folgenden Codebeispiel wird WdfUsbTargetDeviceRetrieveConfigDescriptor aufgerufen, um die erforderliche Puffergröße abzurufen, WdfMemoryCreate aufgerufen, um ein Speicherobjekt und einen Puffer zu erstellen, und dann WdfUsbTargetDeviceRetrieveConfigDescriptor aufgerufen, um die Konfigurationsinformationen eines Geräts abzurufen.

USHORT  size;
NTSTATUS  ntStatus;
PMY_DEVICE_CONTEXT  myDeviceContext;
PUSB_CONFIGURATION_DESCRIPTOR  configurationDescriptor = NULL;
WDF_OBJECT_ATTRIBUTES  objectAttribs;
WDFMEMORY  memoryHandle;

myDeviceContext = GetDeviceContext(Device);

ntStatus = WdfUsbTargetDeviceRetrieveConfigDescriptor(
                                            myDeviceContext->WdfUsbTargetDevice,
                                            NULL,
                                            &size
                                            );

if (ntStatus != STATUS_BUFFER_TOO_SMALL) {
    return ntStatus;
}

WDF_OBJECT_ATTRIBUTES_INIT(&objectAttribs);
objectAttribs.ParentObject = myDeviceContext->WdfUsbTargetDevice;

ntStatus = WdfMemoryCreate(
                           &objectAttribs,
                           NonPagedPool,
                           POOL_TAG,
                           size,
                           &memoryHandle,
                           (PVOID)&configurationDescriptor
                           );
if (!NT_SUCCESS(ntStatus)) {
    return ntStatus;
}

ntStatus = WdfUsbTargetDeviceRetrieveConfigDescriptor(
                                            myDeviceContext->WdfUsbTargetDevice,
                                            configurationDescriptor,
                                            &size
                                            );
if (!NT_SUCCESS(ntStatus)) {
    return ntStatus;
}

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)