WdfUsbTargetDeviceAllocAndQueryString-Funktion (wdfusb.h)

Artikel
08/08/2023

[Gilt für KMDF und UMDF]

Die WdfUsbTargetDeviceAllocAndQueryString-Methode weist einen Puffer zu und ruft dann die Unicode-Zeichenfolge ab, die einem angegebenen USB-Gerät und einem angegebenen Deskriptorindexwert zugeordnet ist.

Syntax

NTSTATUS WdfUsbTargetDeviceAllocAndQueryString(
  [in]            WDFUSBDEVICE           UsbDevice,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES StringMemoryAttributes,
  [out]           WDFMEMORY              *StringMemory,
  [out, optional] PUSHORT                NumCharacters,
  [in]            UCHAR                  StringIndex,
  [in, optional]  USHORT                 LangID
);

Parameter

[in] UsbDevice

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

[in, optional] StringMemoryAttributes

Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_OBJECT_ATTRIBUTES-Struktur , die vom Aufrufer bereitgestellte Attribute für das neue Speicherobjekt enthält. Dieser Parameter ist optional und kann WDF_NO_OBJECT_ATTRIBUTES werden.

[out] StringMemory

Ein Zeiger auf einen Speicherort, der ein Handle für das Speicherobjekt empfängt, das die Unicode-Zeichenfolge enthält. Die Zeichenfolge ist nur dann NULL-beendet, wenn das Gerät eine Zeichenfolge mit NULL-Beendigung bereitstellt.

[out, optional] NumCharacters

Ein Zeiger auf eine Position, die die Anzahl der Zeichen empfängt, die im Zeichenfolgendeskriptor enthalten sind. Wenn die Unicode-Zeichenfolge NULL-beendet ist, enthält diese Zahl das NULL-Zeichen. Dieser Parameter ist optional und kann NULL sein.

[in] StringIndex

Ein Indexwert, der die Unicode-Zeichenfolge identifiziert. Dieser Indexwert wird aus einer USB_DEVICE_DESCRIPTOR-, USB_CONFIGURATION_DESCRIPTOR- oder USB_INTERFACE_DESCRIPTOR-Struktur abgerufen.

[in, optional] LangID

Ein Sprachbezeichner. Die Unicode-Zeichenfolge wird für die Sprache abgerufen, die dieser Bezeichner angibt. Informationen zum Abrufen der unterstützten Sprachbezeichner eines Geräts finden Sie in der USB-Spezifikation.

Rückgabewert

WdfUsbTargetDeviceAllocAndQueryString 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_PARAMETER	Ein ungültiger Parameter wurde erkannt.
STATUS_INSUFFICIENT_RESOURCES	Ein Speicherpuffer konnte nicht zugeordnet werden.
STATUS_DEVICE_DATA_ERROR	Das USB-Gerät hat einen ungültigen Deskriptor zurückgegeben.
STATUS_BUFFER_OVERFLOW	Der bereitgestellte Puffer war zu klein.

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 WdfUsbTargetDeviceAllocAndQueryString-Methode , die Ihr Treiber nur einmal aufrufen muss, um einen Zeichenfolgendeskriptor abzurufen, ist eine Alternative zur WdfUsbTargetDeviceQueryString-Methode , die zweimal aufgerufen werden muss, um eine Zeichenfolge abzurufen.

Die -Methode sucht den angegebenen USB-Zeichenfolgendeskriptor, kopiert die Unicode-Zeichenfolge aus dem Deskriptor in ein Speicherobjekt und gibt ein Handle an das Speicherobjekt zurück.

Nach dem Aufrufen von WdfUsbTargetDeviceAllocAndQueryString kann Ihr Treiber das StringMemory-Handle an WdfMemoryGetBuffer übergeben, um auf den Inhalt des Speicherobjekts zuzugreifen.

Weitere Informationen zu USB-Zeichenfolgendeskriptoren finden Sie in der USB-Spezifikation.

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

Beispiele

Im folgenden Codebeispiel wird WdfUsbTargetDeviceAllocAndQueryString aufgerufen, um die Zeichenfolge des Herstellernamens in US-Englisch (0x0409) von einem USB-Gerätedeskriptor abzurufen. (Der Treiber hat den Deskriptor zuvor im vom Treiber definierten Kontextbereich gespeichert.)

PMY_DEVICE_CONTEXT  myDeviceContext;
WDFMEMORY  memoryHandle;
USHORT  numCharacters;

myDeviceContext = GetDeviceContext(device);

status = WdfUsbTargetDeviceAllocAndQueryString(
                                        myDeviceContext->UsbTargetDevice,
                                        WDF_NO_OBJECT_ATTRIBUTES,
                                        &memoryHandle,
                                        &numCharacters,
                                        myDeviceContext->UsbDeviceDescr.iManufacturer,
                                        0x0409
                                        );

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)