WdfUsbTargetDeviceAllocAndQueryString-Funktion (wdfusb.h)

Artikel
02/07/2025

[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 zugeordnet ist, und den Indexwert des Deskriptors.

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 WdfUsbTargetDeviceCreateWithParametersabgerufen 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 eine Position, die ein Handle für das Speicherobjekt empfängt, das die Unicode-Zeichenfolge enthält. Die Zeichenfolge ist nur NULL-beendet, wenn das Gerät eine NULL-beendete Zeichenfolge 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-werden.

[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

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-Wertezurückgeben.

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

Bemerkungen

Die WdfUsbTargetDeviceAllocAndQueryString--Methode, die der Treiber nur einmal aufrufen muss, um einen Zeichenfolgendeskriptor abzurufen, ist eine Alternative zum 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 WdfUsbTargetDeviceAllocAndQueryStringkann 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 Namenszeichenfolge eines Herstellers in USA (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-	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)