WdfUsbTargetDeviceQueryString-Funktion (wdfusb.h)

Artikel
08/08/2023

[Gilt für KMDF und UMDF]

Die WdfUsbTargetDeviceQueryString-Methode ruft die Unicode-Zeichenfolge ab, die einem angegebenen USB-Gerät und einem angegebenen Deskriptorindexwert zugeordnet ist.

Syntax

NTSTATUS WdfUsbTargetDeviceQueryString(
  [in]            WDFUSBDEVICE              UsbDevice,
  [in, optional]  WDFREQUEST                Request,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [out, optional] PUSHORT                   String,
  [in, out]       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] Request

Ein Handle für ein Frameworkanforderungsobjekt. Dieser Parameter ist optional und kann NULL sein. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in, optional] RequestOptions

Ein Zeiger auf eine vom Aufrufer zugeordnete WDF_REQUEST_SEND_OPTIONS Struktur, die Optionen für die Anforderung angibt. Dieser Zeiger ist optional und kann NULL sein. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[out, optional] String

Ein Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der die angeforderte Unicode-Zeichenfolge empfängt. Die Zeichenfolge ist nur dann NULL-beendet, wenn das Gerät eine Zeichenfolge mit NULL-Beendigung bereitstellt. Wenn dieser Zeiger NULL ist, gibt WdfUsbTargetDeviceQueryString die erforderliche Puffergröße (d. h. die erforderliche Anzahl von Unicode-Zeichen) an der Position zurück, auf die NumCharacters zeigt.

[in, out] NumCharacters

Ein Zeiger auf eine vom Aufrufer zugeordnete Variable. Der Aufrufer gibt die Anzahl der Unicode-Zeichen an, die der Puffer enthalten kann. Wenn WdfUsbTargetDeviceQueryString zurückgibt, empfängt die Variable die Anzahl der Zeichen (einschließlich des NULL-Abschlusszeichens, falls angegeben), die sich in der Unicode-Zeichenfolge befinden, die der String-Puffer empfängt.

[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

WdfUsbTargetDeviceQueryString 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

Treiber sollten WdfUsbTargetDeviceQueryString zweimal aufrufen, indem sie die folgenden Schritte ausführen:

Legen Sie den String-Zeiger auf NULL fest, sodass WdfUsbTargetDeviceQueryString die erforderliche Puffergröße in der Adresse zurückgibt, auf die der NumCharacters-Parameter zeigt.
Weisen Sie Pufferspeicherplatz zu, um die Anzahl der Unicode-Zeichen in der angeforderten Zeichenfolge zu speichern. Beispielsweise kann ein Treiber ExAllocatePoolWithTag aufrufen, um einen Puffer zuzuweisen, oder er könnte WdfMemoryCreate aufrufen, um ein Frameworkspeicherobjekt zu erstellen.
Rufen Sie WdfUsbTargetDeviceQueryString erneut auf, und legen Sie den String-Wert auf einen Zeiger auf den neuen Puffer fest, und legen Sie NumCharacters auf die Länge des Puffers fest (d. h. die Anzahl der Unicode-Zeichen, nicht die Bytelänge).

WdfUsbTargetDeviceQueryString sucht den angegebenen USB-Zeichenfolgendeskriptor und kopiert die Unicode-Zeichenfolge aus dem Deskriptor in den angegebenen Puffer.

Wenn Der Treiber einen Wert ungleich NULL für den Request-Parameter angibt, verwendet das Framework das angegebene Anforderungsobjekt, und ein anderer Treiberthread kann WdfRequestCancelSentRequest aufrufen, falls erforderlich, um zu versuchen, die Zeichenfolgenabfrageanforderung abzubrechen. Wenn der Treiber einen NULL-Wert für Request angibt, verwendet das Framework ein internes Anforderungsobjekt, das der Treiber nicht abbrechen kann.

Ihr Treiber kann einen RequestOptions-Parameter ungleich NULL angeben, unabhängig davon, ob der Treiber einen Nicht-NULL- oder null-Anforderungsparameter bereitstellt. Sie können beispielsweise den Parameter RequestOptions verwenden, um einen Timeoutwert anzugeben.

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

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

Beispiele

Im folgenden Codebeispiel wird WdfUsbTargetDeviceQueryString aufgerufen, um die erforderliche Puffergröße zu erhalten, WdfMemoryCreate aufgerufen, um ein Speicherobjekt und einen Puffer zu erstellen, und dann WdfUsbTargetDeviceQueryString aufgerufen, um die Namenszeichenfolge des Herstellers 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;
USHORT  numCharacters;
PUSHORT  stringBuf;
WDFMEMORY  memoryHandle;

myDeviceContext = GetDeviceContext(device);

status = WdfUsbTargetDeviceQueryString(
                                       myDeviceContext->UsbTargetDevice,
                                       NULL,
                                       NULL,
                                       NULL,
                                       &numCharacters,
                                       myDeviceContext->UsbDeviceDescr.iManufacturer,
                                       0x0409
                                       );

ntStatus = WdfMemoryCreate(
                           WDF_NO_OBJECT_ATTRIBUTES,
                           NonPagedPool,
                           POOL_TAG,
                           numCharacters * sizeof(WCHAR),
                           &memoryHandle,
                           (PVOID)&stringBuf
                           );
if (!NT_SUCCESS(ntStatus)) {
    return ntStatus;
}
status = WdfUsbTargetDeviceQueryString(
                                       myDeviceContext->UsbTargetDevice,
                                       NULL,
                                       NULL,
                                       stringBuf,
                                       &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)