WdfUsbTargetDeviceAllocAndQueryString-Funktion (wdfusb.h)

[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 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 zu einem USB-Geräteobjekt, das von einem vorherigen Aufruf von WdfUsbTargetDeviceCreateWithParameters abgerufen wurde.

[in, optional] StringMemoryAttributes

Ein Zeiger auf eine aufgerufene WDF_OBJECT_ATTRIBUTES Struktur, die 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 an 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 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 zugewiesen 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 der 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 einen Handle an das Speicherobjekt zurück.

Nachdem Sie WdfUsbTargetDeviceAllocAndQueryString aufgerufen haben, 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-I/O-Zielen finden Sie unter USB-I/O-Ziele.

Beispiele

Im folgenden Codebeispiel wird WdfUsbTargetDeviceAllocAndQueryString aufgerufen, um die Namezeichenfolge eines Herstellers in USA (0x0409) von einem USB-Gerätedeskriptor abzurufen. (Der Treiber hat zuvor den Deskriptor 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

   
Zielplattform Universell
KMDF-Mindestversion 1.0
UMDF-Mindestversion 2.0
Header wdfusb.h (include 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)

Weitere Informationen

USB_CONFIGURATION_DESCRIPTOR

USB_DEVICE_DESCRIPTOR

USB_INTERFACE_DESCRIPTOR

WDF_OBJECT_ATTRIBUTES

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceQueryString