Función WdfUsbTargetDeviceQueryString (wdfusb.h)

Artículo
08/08/2023

[Se aplica a KMDF y UMDF]

El método WdfUsbTargetDeviceQueryString recupera la cadena Unicode asociada a un valor de índice de descriptor y dispositivo USB especificado.

Sintaxis

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

Parámetros

[in] UsbDevice

Identificador de un objeto de dispositivo USB obtenido de una llamada anterior a WdfUsbTargetDeviceCreateWithParameters.

[in, optional] Request

Identificador de un objeto de solicitud de marco. Este parámetro es opcional y puede ser NULL. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

[in, optional] RequestOptions

Puntero a una estructura de WDF_REQUEST_SEND_OPTIONS asignada por el autor de la llamada que especifica las opciones de la solicitud. Este puntero es opcional y puede ser NULL. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

[out, optional] String

Puntero a un búfer asignado por el autor de la llamada que recibe la cadena Unicode solicitada. La cadena solo termina en NULL si el dispositivo proporciona una cadena terminada en NULL. Si este puntero es NULL, WdfUsbTargetDeviceQueryString devuelve el tamaño de búfer necesario (es decir, el número necesario de caracteres Unicode) en la ubicación a la que apunta NumCharacters .

[in, out] NumCharacters

Puntero a una variable asignada por el autor de la llamada. El autor de la llamada proporciona el número de caracteres Unicode que el búfer puede contener. Cuando WdfUsbTargetDeviceQueryString devuelve, la variable recibe el número de caracteres (incluido el terminador NULL, si se proporciona) que se encuentran en la cadena Unicode que recibe el búfer string .

[in] StringIndex

Valor de índice que identifica la cadena Unicode. Este valor de índice se obtiene de una estructura USB_DEVICE_DESCRIPTOR, USB_CONFIGURATION_DESCRIPTOR o USB_INTERFACE_DESCRIPTOR .

[in, optional] LangID

Identificador de idioma. La cadena Unicode se recuperará para el idioma que especifica este identificador. Para obtener información sobre cómo obtener los identificadores de idioma admitidos de un dispositivo, consulte la especificación USB.

Valor devuelto

WdfUsbTargetDeviceQueryString devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, este método puede devolver uno de los valores siguientes:

Código devuelto	Descripción
STATUS_INVALID_PARAMETER	Se ha detectado un parámetro no válido.
STATUS_INSUFFICIENT_RESOURCES	No se pudo asignar un búfer de memoria.
STATUS_DEVICE_DATA_ERROR	El dispositivo USB devolvió un descriptor no válido.
STATUS_BUFFER_OVERFLOW	El búfer proporcionado era demasiado pequeño.

Este método también podría devolver otros valores NTSTATUS.

Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.

Comentarios

Los controladores deben llamar a WdfUsbTargetDeviceQueryString dos veces, mediante los pasos siguientes:

Establezca el puntero String en NULL, de modo que WdfUsbTargetDeviceQueryString devuelva el tamaño de búfer necesario en la dirección a la que apunta el parámetro NumCharacters .
Asigne espacio de búfer para contener el número de caracteres Unicode que se encuentran en la cadena solicitada. Por ejemplo, un controlador podría llamar a ExAllocatePoolWithTag para asignar un búfer o podría llamar a WdfMemoryCreate para crear un objeto de memoria del marco.
Vuelva a llamar a WdfUsbTargetDeviceQueryString , estableciendo el valor string en un puntero al nuevo búfer y estableciendo NumCharacters en la longitud del búfer (es decir, el número de caracteres Unicode, no la longitud del byte).

WdfUsbTargetDeviceQueryString busca el descriptor de cadena USB especificado y copia la cadena Unicode del descriptor en el búfer proporcionado.

Si el controlador especifica un valor distinto de NULL para el parámetro Request , el marco usa el objeto de solicitud especificado y otro subproceso de controlador puede llamar a WdfRequestCancelSentRequest, si es necesario, para intentar cancelar la solicitud de consulta de cadena. Si el controlador especifica un valor NULL para Request, el marco usa un objeto de solicitud interno que el controlador no puede cancelar.

El controlador puede especificar un parámetro RequestOptions que no sea NULL, ya sea que el controlador proporcione un parámetro request distinto de NULL o NULL. Por ejemplo, puede usar el parámetro RequestOptions para especificar un valor de tiempo de espera.

Para obtener más información sobre los descriptores de cadena USB, consulte la especificación USB.

Para obtener más información sobre el método WdfUsbTargetDeviceQueryString y los destinos de E/S USB, consulte Destinos de E/S USB.

Ejemplos

En el ejemplo de código siguiente se llama a WdfUsbTargetDeviceQueryString para obtener el tamaño de búfer necesario, llama a WdfMemoryCreate para crear un objeto de memoria y un búfer y, a continuación, llama a WdfUsbTargetDeviceQueryString de nuevo para obtener la cadena de nombre del fabricante, en inglés de EE. UU. (0x0409), desde un descriptor de dispositivo USB. (El controlador almacenó previamente el descriptor en el espacio de contexto definido por el controlador).

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

Requisitos

Requisito	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Versión mínima de UMDF	2.0
Encabezado	wdfusb.h (incluya Wdfusb.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)