WdfUsbTargetDeviceQueryString-Funktion (wdfusb.h)

Artikel
07/16/2024

[Gilt für KMDF und UMDF]

Die WdfUsbTargetDeviceQueryString--Methode ruft die Unicode-Zeichenfolge ab, die einem angegebenen USB-Gerät und einem Indexwert des Deskriptors 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 WdfUsbTargetDeviceCreateWithParametersabgerufen wurde.

[in, optional] Request

Ein Handle zu einem Framework-Anforderungsobjekt. Dieser Parameter ist optional und kann NULL-werden. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in, optional] RequestOptions

Ein Zeiger auf eine vom Aufrufer zugewiesene 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 NULL-beendet, wenn das Gerät eine NULL-beendete Zeichenfolge 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 verweist.

[in, out] NumCharacters

Ein Zeiger auf eine vom Aufrufer zugewiesene Variable. Der Aufrufer stellt die Anzahl der Unicode-Zeichen zur Auswahl, die der Puffer enthalten kann. Wenn WdfUsbTargetDeviceQueryString- zurückgegeben wird, empfängt die Variable die Anzahl der Zeichen (einschließlich des NULL-Terminators, 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_DESCRIPTORoder 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 Sprach-IDs 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-Wertezurückgeben.

Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.

Bemerkungen

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 verweist.
Weisen Sie Pufferspeicher zu, um die Anzahl der Unicode-Zeichen in der angeforderten Zeichenfolge 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 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. a. 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 bereitgestellten Puffer.

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

Der Treiber kann einen Parameter ohneNULL-RequestOptions- angeben, unabhängig davon, ob der Treiber ein nicht-NULL- oder ein NULL-Request Parameter bereitstellt. Sie können z. B. 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 I/O Targets.

Beispiele

Im folgenden Codebeispiel wird WdfUsbTargetDeviceQueryString aufgerufen, um die erforderliche Puffergröße abzurufen, ruft WdfMemoryCreate auf, um ein Speicherobjekt und einen Puffer zu erstellen, und ruft dann WdfUsbTargetDeviceQueryString erneut auf, um die Namenszeichenfolge des Herstellers in den USA (0x0409) aus 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-	Universal
Minimale KMDF-Version	1.0
Mindest-UMDF-Version	2.0
Header-	wdfusb.h (include Wdfusb.h)
Library	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)