Funzione WdfUsbTargetDeviceQueryString (wdfusb.h)

Articolo
08/08/2023

[Si applica a KMDF e UMDF]

Il metodo WdfUsbTargetDeviceQueryString recupera la stringa Unicode associata a un dispositivo USB e un valore di indice del descrittore specificato.

Sintassi

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

Parametri

[in] UsbDevice

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

[in, optional] Request

Handle per un oggetto richiesta framework. Questo parametro è facoltativo e può essere NULL. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[in, optional] RequestOptions

Puntatore a una struttura WDF_REQUEST_SEND_OPTIONS allocata dal chiamante che specifica le opzioni per la richiesta. Questo puntatore è facoltativo e può essere NULL. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[out, optional] String

Puntatore a un buffer allocato del chiamante che riceve la stringa Unicode richiesta. La stringa viene terminata null solo se il dispositivo fornisce una stringa con terminazione NULL. Se questo puntatore è NULL, WdfUsbTargetDeviceQueryString restituisce le dimensioni del buffer necessarie, ovvero il numero richiesto di caratteri Unicode, nella posizione a cui punta NumCharacters .

[in, out] NumCharacters

Puntatore a una variabile allocata dal chiamante. Il chiamante fornisce il numero di caratteri Unicode che il buffer può contenere. Quando WdfUsbTargetDeviceQueryString restituisce, la variabile riceve il numero di caratteri (incluso il terminatore NULL, se specificato) nella stringa Unicode ricevuta dal buffer String .

[in] StringIndex

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

[in, optional] LangID

Identificatore della lingua. La stringa Unicode verrà recuperata per la lingua specificata da questo identificatore. Per informazioni sull'acquisizione degli identificatori di lingua supportati di un dispositivo, vedere la specifica USB.

Valore restituito

WdfUsbTargetDeviceQueryString 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 restituire anche altri valori NTSTATUS.

Un controllo di bug si verifica se il driver fornisce un handle di oggetti non valido.

Commenti

I driver devono chiamare WdfUsbTargetDeviceQueryString due volte, seguendo questa procedura:

Impostare il puntatore String su NULL, in modo che WdfUsbTargetDeviceQueryString restituirà le dimensioni del buffer necessarie nell'indirizzo a cui punta il parametro NumCharacters .
Allocare spazio buffer per contenere il numero di caratteri Unicode presenti nella stringa richiesta. Ad esempio, un driver potrebbe chiamare ExAllocatePoolWithTag per allocare un buffer oppure chiamare WdfMemoryCrea per creare un oggetto memoria framework.
Chiamare di nuovo WdfUsbTargetDeviceQueryString, impostando il valore String su un puntatore al nuovo buffer e impostando NumCharacters sulla lunghezza del buffer, ovvero il numero di caratteri Unicode, non la lunghezza di byte.

WdfUsbTargetDeviceQueryString individua il descrittore di stringa USB specificato e copia la stringa Unicode dal descrittore nel buffer fornito.

Se il driver specifica un valore non NULL per il parametro Request, il framework usa l'oggetto request specificato e un altro thread driver può chiamare WdfRequestCancelSentRequest, se necessario, per tentare di annullare la richiesta di query stringa. Se il driver specifica un valore NULL per Request, il framework usa un oggetto request interno che il driver non può annullare.

Il driver può specificare un parametroRequestOptions diverso da NULL, indipendentemente dal fatto che il driver fornisca un parametro non NULL o null Request. È possibile, ad esempio, usare il parametro RequestOptions per specificare un valore di timeout.

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

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

Esempio

L'esempio di codice seguente chiama WdfUsbTargetDeviceQueryString per ottenere le dimensioni del buffer necessarie, chiama WdfMemoryCrea per creare un oggetto e un buffer di memoria e quindi chiama di nuovo WdfUsbTargetDeviceQueryString per ottenere la stringa nome del produttore, in inglese usa (0x0409), da un descrittore del dispositivo USB. Il driver in precedenza archiviò il descrittore nello spazio di contesto definito dal driver.

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

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.0
Versione UMDF minima	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)