Función WdfUsbTargetDeviceQueryString (wdfusb.h)
[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 se puede NULL. Para obtener más información, vea la siguiente sección Comentarios.
[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 se puede NULL. Para obtener más información, vea la siguiente sección Comentarios.
[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 NumCharacters apunta.
[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 puede contener el búfer. 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 de 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_DESCRIPTORo 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 siguientes valores:
Código devuelto | Descripción |
---|---|
|
Se detectó un parámetro no válido. |
|
No se pudo asignar un búfer de memoria. |
|
El dispositivo USB devolvió un descriptor no válido. |
|
El búfer proporcionado era demasiado pequeño. |
Este método también puede devolver otros valores de NTSTATUS.
Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.
Observaciones
Los controladores deben llamar a WdfUsbTargetDeviceQueryString dos veces, mediante los pasos siguientes:
-
Establezca el puntero string de
en NULL, de modo que WdfUsbTargetDeviceQueryString devolverá el tamaño de búfer necesario en la dirección a la que apunta el parámetroNumCharacters . - 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 de marco.
- Llame a WdfUsbTargetDeviceQueryString de nuevo, estableciendo el valor String en un puntero al nuevo búfer y estableciendo NumCharacters a la longitud del búfer (es decir, el número de caracteres Unicode, no la longitud del byte).
Si el controlador especifica un valor null que no es
El controlador puede especificar un parámetro requestOptions que no sea
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 búfer y, a continuación, llama a WdfUsbTargetDeviceQueryString 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 | Valor |
---|---|
de la plataforma de destino de |
Universal |
versión mínima de KMDF | 1.0 |
versión mínima de UMDF | 2.0 |
encabezado de |
wdfusb.h (incluya Wdfusb.h) |
biblioteca de |
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) |