Funzione WdfUsbTargetDeviceAllocAndQueryString (wdfusb.h)

Articolo
02/07/2025

[Si applica a KMDF e UMDF]

Il metodo WdfUsbTargetDeviceAllocAndQueryString alloca un buffer, quindi recupera la stringa Unicode associata a un dispositivo USB e un valore di indice del descrittore specificati.

Sintassi

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
);

Parametri

[in] UsbDevice

Handle per un oggetto dispositivo USB ottenuto da una chiamata precedente a WdfUsbTargetDeviceCreateWithParameters.

[in, optional] StringMemoryAttributes

Puntatore a una struttura WDF_OBJECT_ATTRIBUTES allocata dal chiamante che contiene gli attributi forniti dal chiamante per il nuovo oggetto memoria. Questo parametro è facoltativo e può essere WDF_NO_OBJECT_ATTRIBUTES.

[out] StringMemory

Puntatore a una posizione che riceve un handle per l'oggetto memoria che contiene la stringa Unicode. La stringa è con terminazione NULL solo se il dispositivo fornisce una stringa con terminazione NULL.

[out, optional] NumCharacters

Puntatore a una posizione che riceve il numero di caratteri contenuti nel descrittore di stringa. Se la stringa Unicode è con terminazione NULL, questo numero include il carattere NULL. Questo parametro è facoltativo e può essere NULL.

[in] StringIndex

Valore di indice che identifica la stringa Unicode. Questo valore di indice viene ottenuto da una struttura USB_DEVICE_DESCRIPTOR, USB_CONFIGURATION_DESCRIPTORo USB_INTERFACE_DESCRIPTOR.

[in, optional] LangID

Identificatore di lingua. La stringa Unicode verrà recuperata per la lingua specificata da questo identificatore. Per informazioni su come ottenere gli identificatori di lingua supportati di un dispositivo, vedere la specifica USB.

Valore restituito

WdfUsbTargetDeviceAllocAndQueryString restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo può restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	È stato rilevato un parametro non valido.
STATUS_INSUFFICIENT_RESOURCES	Impossibile allocare un buffer di memoria.
STATUS_DEVICE_DATA_ERROR	Il dispositivo USB ha restituito un descrittore non valido.
STATUS_BUFFER_OVERFLOW	Il buffer fornito era troppo piccolo.

Questo metodo potrebbe anche restituire altri valori NTSTATUS .

Se il driver fornisce un handle di oggetto non valido, si verifica un controllo di bug.

Osservazioni

Il metodo WdfUsbTargetDeviceAllocAndQueryString, che il driver deve chiamare una sola volta per ottenere un descrittore di stringa, è un'alternativa al metodo WdfUsbTargetDeviceQueryString, che deve essere chiamato due volte per ottenere una stringa.

Il metodo individua il descrittore di stringa USB specificato, copia la stringa Unicode dal descrittore in un oggetto memory e restituisce un handle all'oggetto memory.

Dopo aver chiamato WdfUsbTargetDeviceAllocAndQueryString, il driver può passare l'handle StringMemory per WdfMemoryGetBuffer per accedere al contenuto dell'oggetto memoria.

Per altre informazioni sui descrittori di stringhe USB, vedere la specifica USB.

Per altre informazioni sul metodo di WdfUsbTargetDeviceAllocAndQueryString e sulle destinazioni di I/O USB, vedere Destinazioni I/O USB.

Esempi

L'esempio di codice seguente chiama WdfUsbTargetDeviceAllocAndQueryString per ottenere la stringa del nome di un produttore, in inglese usa (0x0409) da un descrittore di dispositivo USB. Il driver in precedenza archiviò il descrittore nello spazio di contesto definito dal driver.

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
                                        );

Fabbisogno

Requisito	Valore
piattaforma di destinazione	Universale
versione minima di KMDF	1.0
versione minima di UMDF	2.0
intestazione	wdfusb.h (include Wdfusb.h)
libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)