Función WdfUsbTargetDeviceAllocAndQueryString (wdfusb.h)

[Se aplica a KMDF y UMDF]

El método WdfUsbTargetDeviceAllocAndQueryString asigna un búfer y, a continuación, recupera la cadena Unicode asociada a un valor de índice de descriptor y dispositivo USB especificado.

Sintaxis

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

Parámetros

[in] UsbDevice

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

[in, optional] StringMemoryAttributes

Puntero a una estructura de WDF_OBJECT_ATTRIBUTES asignada por el autor de la llamada que contiene atributos proporcionados por el autor de la llamada para el nuevo objeto de memoria. Este parámetro es opcional y puede ser WDF_NO_OBJECT_ATTRIBUTES.

[out] StringMemory

Puntero a una ubicación que recibe un identificador para el objeto de memoria que contiene la cadena Unicode. La cadena solo termina en NULL si el dispositivo proporciona una cadena terminada en NULL.

[out, optional] NumCharacters

Puntero a una ubicación que recibe el número de caracteres contenidos en el descriptor de cadena. Si la cadena Unicode termina en NULL, este número incluye el carácter NULL. Este parámetro es opcional y puede ser NULL.

[in] StringIndex

Valor de índice que identifica la cadena Unicode. Este valor de índice se obtiene de una estructura de 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

WdfUsbTargetDeviceAllocAndQueryString 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.

Observaciones

El método WdfUsbTargetDeviceAllocAndQueryString , al que el controlador solo debe llamar una vez para obtener un descriptor de cadena, es una alternativa al método WdfUsbTargetDeviceQueryString , al que se debe llamar dos veces para obtener una cadena.

El método busca el descriptor de cadena USB especificado, copia la cadena Unicode del descriptor en un objeto de memoria y devuelve un identificador al objeto de memoria.

Después de llamar a WdfUsbTargetDeviceAllocAndQueryString, el controlador puede pasar el identificador StringMemory a WdfMemoryGetBuffer para tener acceso al contenido del objeto de memoria.

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 WdfUsbTargetDeviceAllocAndQueryString y los destinos de E/S USB, consulte Destinos de E/S USB.

Ejemplos

En el ejemplo de código siguiente se llama a WdfUsbTargetDeviceAllocAndQueryString para obtener la cadena de nombre de un 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;
WDFMEMORY  memoryHandle;
USHORT  numCharacters;

myDeviceContext = GetDeviceContext(device);

status = WdfUsbTargetDeviceAllocAndQueryString(
                                        myDeviceContext->UsbTargetDevice,
                                        WDF_NO_OBJECT_ATTRIBUTES,
                                        &memoryHandle,
                                        &numCharacters,
                                        myDeviceContext->UsbDeviceDescr.iManufacturer,
                                        0x0409
                                        );

Requisitos

   
Plataforma de destino Universal
Versión mínima de KMDF 1,0
Versión mínima de UMDF 2,0
Header 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)

Vea también

USB_CONFIGURATION_DESCRIPTOR

USB_DEVICE_DESCRIPTOR

USB_INTERFACE_DESCRIPTOR

WDF_OBJECT_ATTRIBUTES

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceQueryString