Funzione WdfUsbTargetDeviceQueryString (wdfusb.h)

Articolo
07/16/2024

[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 specificati.

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 per 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 altre informazioni, vedere la sezione Osservazioni seguente.

[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 altre informazioni, vedere la sezione Osservazioni seguente.

[out, optional] String

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

[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 carattere di terminazione 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_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

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

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

Osservazioni

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 del buffer per contenere il numero di caratteri Unicode presenti nella stringa richiesta. Ad esempio, un driver potrebbe chiamare ExAllocatePoolWithTag per allocare un buffer oppure potrebbe chiamare WdfMemoryCreate per creare un oggetto memoria del 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 dei 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 NULL nonper il parametro request , il framework usa l'oggetto richiesta specificato e un altro thread del driver può chiamare WdfRequestCancelSentRequest, se necessario, per tentare di annullare la richiesta di query di stringa. Se il driver specifica un valore NULL per Request, il framework usa un oggetto richiesta interno che il driver non può annullare.

Il driver può specificare un parametro nullNULLnull, indipendentemente dal fatto che il driver fornisca un NULL nono un parametro RequestNULL . È ad esempio possibile usare il parametro RequestOptions per specificare un valore di timeout.

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

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

Esempi

L'esempio di codice seguente chiama WdfUsbTargetDeviceQueryString per ottenere le dimensioni del buffer necessarie, chiama WdfMemoryCreare per creare un oggetto e un buffer di memoria e quindi chiama WdfUsbTargetDeviceQueryString per ottenere nuovamente la stringa del nome del produttore, in inglese (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;
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
                                       );

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)