Función WdfRegistryQueryMultiString (wdfregistry.h)

Artículo
02/27/2024

[Se aplica a KMDF y UMDF]

El método WdfRegistryQueryMultiString recupera las cadenas asignadas actualmente a un valor de registro de varias cadenas especificado, crea un objeto de cadena de marco para cada cadena y agrega cada objeto de cadena a una colección de objetos especificada.

Sintaxis

NTSTATUS WdfRegistryQueryMultiString(
  [in]           WDFKEY                 Key,
  [in]           PCUNICODE_STRING       ValueName,
  [in, optional] PWDF_OBJECT_ATTRIBUTES StringsAttributes,
  [in]           WDFCOLLECTION          Collection
);

Parámetros

[in] Key

Identificador de un objeto de clave del Registro que representa una clave del Registro abierta.

[in] ValueName

Puntero a una estructura UNICODE_STRING que contiene un nombre de valor.

[in, optional] StringsAttributes

Puntero a una estructura WDF_OBJECT_ATTRIBUTES que contiene atributos de objeto para cada nuevo objeto de cadena. Este parámetro es opcional y puede ser WDF_NO_OBJECT_ATTRIBUTES.

[in] Collection

Identificador de un objeto de colección de marcos proporcionado por el controlador.

Valor devuelto

WdfRegistryQueryMultiString devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, el método podría devolver uno de los siguientes valores:

Código devuelto	Descripción
STATUS_INVALID_DEVICE_REQUEST	No se llamó a WdfRegistryQueryMultiString en IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	Se especificó un parámetro no válido.
STATUS_INSUFFICIENT_RESOURCES	No se pudo asignar un objeto de cadena.
STATUS_ACCESS_DENIED	El controlador no abrió la clave del Registro con acceso KEY_QUERY_VALUE, KEY_READ o KEY_ALL_ACCESS.
STATUS_OBJECT_TYPE_MISMATCH	Tipo de datos del valor del Registro que no se especificó el parámetro ValueName REG_MULTI_SZ.
STATUS_OBJECT_NAME_NOT_FOUND	El valor del Registro no estaba disponible.
STATUS_RESOURCE_DATA_NOT_FOUND	El valor del Registro existe bajo la clave especificada, pero está vacío.

Para obtener una lista de otros valores devueltos que puede devolver el método WdfRegistryQueryMultiString , vea Errores de creación de objetos de marco.

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

Antes de que el controlador llame a WdfRegistryQueryMultiString, debe llamar a WdfCollectionCreate para crear un objeto de colección.

Si el autor de la llamada no proporciona un parámetro StringsAttributes , los objetos WDFSTRING creados por el marco están primarios de forma predeterminada en WDFDRIVER.

Después de que WdfRegistryQueryMultiString vuelva, el controlador puede llamar a WdfCollectionGetCount para obtener el número de cadenas recuperadas y WdfCollectionGetItem para obtener objetos de cadena de la colección.

Si la colección contiene objetos antes de que el controlador llame al método WdfRegistryQueryMultiString , el método no quita esos objetos ni cambia sus valores de índice. Los nuevos objetos se anexan al final de la colección.

Para obtener una cadena de un objeto de cadena, el controlador puede llamar a WdfStringGetUnicodeString.

Para obtener más información sobre los objetos de clave del Registro, vea Uso del Registro en controladores de Framework-Based.

Ejemplos

En el ejemplo de código siguiente se crea un objeto de colección, se inicializa una estructura de WDF_OBJECT_ATTRIBUTES para que el objeto de colección sea el elemento primario de todos los objetos de cadena que crea el marco para la colección y recupera las cadenas de un valor del Registro de varias cadenas. Por último, en el ejemplo se obtiene el número de objetos de cadena que el marco de trabajo agregó a la colección.

WDF_OBJECT_ATTRIBUTES stringAttributes;
WDFCOLLECTION col;
NTSTATUS status;
ULONG count;
DECLARE_CONST_UNICODE_STRING(valueMultiSz, VALUE_MULTI_SZ);

status = WdfCollectionCreate(
                             NULL,
                             &col
                             );
ASSERT(NT_SUCCESS(status));

WDF_OBJECT_ATTRIBUTES_INIT(&stringAttributes);
stringAttributes.ParentObject = col;

status = WdfRegistryQueryMultiString(
                                     Key,
                                     &valueMultiSzEmpty,
                                     &stringAttributes,
                                     col
                                     );

count = WdfCollectionGetCount(col);

Requisitos

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