Función WdfRegistryQueryUnicodeString (wdfregistry.h)

Artículo
08/08/2023

[Se aplica a KMDF y UMDF]

El método WdfRegistryQueryUnicodeString recupera los datos de cadena asignados actualmente a un valor de cadena del Registro especificado y copia la cadena en una estructura de UNICODE_STRING especificada.

Sintaxis

NTSTATUS WdfRegistryQueryUnicodeString(
  [in]            WDFKEY           Key,
  [in]            PCUNICODE_STRING ValueName,
  [out, optional] PUSHORT          ValueByteLength,
  [in, out]       PUNICODE_STRING  Value
);

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 de UNICODE_STRING que contiene un nombre para el valor del Registro.

[out, optional] ValueByteLength

Puntero a una ubicación que recibe el número de bytes contenidos en la cadena Unicode a la que apunta Value , incluido el byte NULL de terminación. Este puntero es opcional y puede ser NULL.

[in, out] Value

Puntero a una estructura de UNICODE_STRING que recibe la cadena de datos de la clave que especifica Key . Si este parámetro es NULL y ValueByteLength no es NULL, WdfRegistryQueryUnicodeString devuelve solo el tamaño de la cadena.

Valor devuelto

WdfRegistryQueryUnicodeString 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 WdfRegistryQueryUnicodeString en IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	Se especificó un parámetro no válido.
STATUS_INSUFFICIENT_RESOURCES	No había memoria suficiente para completar la operación.
STATUS_ACCESS_DENIED	El controlador no ha abierto la clave del Registro con KEY_QUERY_VALUE, KEY_READ o acceso KEY_ALL_ACCESS.
STATUS_OBJECT_TYPE_MISMATCH	Tipo de datos del valor del Registro que el parámetro ValueName especificado no se REG_SZ.
STATUS_BUFFER_OVERFLOW	El búfer al que apunta el parámetro Value era demasiado pequeño y solo se escribieron datos parciales en el búfer.
STATUS_BUFFER_OVERFLOW	El búfer al que apunta el parámetro Value era demasiado pequeño y no se escribió ningún dato en el búfer.
STATUS_OBJECT_NAME_NOT_FOUND	El valor del Registro no estaba disponible.

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

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, que procede del controlador de ejemplo serie , se recupera la cadena Unicode que representa los datos de cadena asignados al valor PortName en la clave de hardware de un dispositivo.

NTSTATUS
SerialReadSymName(
    IN WDFDEVICE Device,
    __out PWCHAR RegName,
    IN OUT PUSHORT LengthOfRegName // In characters
    )
{
    NTSTATUS status;
    WDFKEY hKey;
    UNICODE_STRING value;
    UNICODE_STRING valueName;
    USHORT requiredLength;

    value.Buffer = RegName;
    value.MaximumLength = *LengthOfRegName;
    value.Length = 0;

    status = WdfDeviceOpenRegistryKey(
                                      Device,
                                      PLUGPLAY_REGKEY_DEVICE,
                                      STANDARD_RIGHTS_ALL,
                                      WDF_NO_OBJECT_ATTRIBUTES,
                                      &hKey
                                      );

    if (NT_SUCCESS (status)) {
        RtlInitUnicodeString(
                             &valueName,
                             L"PortName"
                             );
        status = WdfRegistryQueryUnicodeString (
                                      hKey,
                                      &valueName,
                                      &requiredLength,
                                      &value
                                      );
        WdfRegistryClose(hKey);
    }
    return status;
}

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 (incluya 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)