Función RegQueryValueExA (winreg.h)

Artículo
06/01/2023

Recupera el tipo y los datos del nombre de valor especificado asociado a una clave del Registro abierta.

Advertencia

Si el valor que se consulta es una cadena (REG_SZ, REG_MULTI_SZ y REG_EXPAND_SZ), no se garantiza que el valor devuelto termine en null. Use la función RegGetValue si desea asegurarse de que los valores de cadena devueltos terminan en null. Más información se encuentra en los comentarios siguientes.

Sintaxis

LSTATUS RegQueryValueExA(
  [in]                HKEY    hKey,
  [in, optional]      LPCSTR  lpValueName,
                      LPDWORD lpReserved,
  [out, optional]     LPDWORD lpType,
  [out, optional]     LPBYTE  lpData,
  [in, out, optional] LPDWORD lpcbData
);

Parámetros

[in] hKey

Identificador de una clave del Registro abierta. La clave debe haberse abierto con el derecho de acceso KEY_QUERY_VALUE. Para obtener más información, consulte Derechos de acceso y seguridad de clave del Registro.

Este identificador lo devuelve la función RegCreateKeyEx, RegCreateKeyTransacted, RegOpenKeyEx o RegOpenKeyTransacted . También puede ser una de las siguientes claves predefinidas:

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_PERFORMANCE_NLSTEXT

HKEY_PERFORMANCE_TEXT

HKEY_USERS

[in, optional] lpValueName

Nombre del valor del Registro.

Si lpValueName es NULL o una cadena vacía, "", la función recupera el tipo y los datos del valor predeterminado o sin nombre de la clave, si existe.

Si lpValueName especifica un valor que no está en el Registro, la función devuelve ERROR_FILE_NOT_FOUND.

Las claves no tienen automáticamente un valor predeterminado o sin nombre. Los valores sin nombre pueden ser de cualquier tipo. Para obtener más información, vea Límites de tamaño de elemento del Registro.

lpReserved

Este parámetro está reservado y debe ser NULL.

[out, optional] lpType

Puntero a una variable que recibe un código que indica el tipo de datos almacenados en el valor especificado. Para obtener una lista de los posibles códigos de tipo, vea Tipos de valor del Registro. El parámetro lpType puede ser NULL si el código de tipo no es necesario.

[out, optional] lpData

Puntero a un búfer que recibe los datos del valor. Este parámetro puede ser NULL si los datos no son necesarios.

[in, out, optional] lpcbData

Puntero a una variable que especifica el tamaño del búfer al que apunta el parámetro lpData , en bytes. Cuando se devuelve la función, esta variable contiene el tamaño de los datos copiados en lpData.

El parámetro lpcbData solo puede ser NULL si lpData es NULL.

Si los datos tienen el REG_SZ, REG_MULTI_SZ o REG_EXPAND_SZ tipo, este tamaño incluye cualquier carácter o caracteres nulos de terminación a menos que los datos se almacenen sin ellos. Para obtener más información, vea la sección Comentarios.

Si el búfer especificado por el parámetro lpData no es lo suficientemente grande como para contener los datos, la función devuelve ERROR_MORE_DATA y almacena el tamaño de búfer necesario en la variable a la que apunta lpcbData. En este caso, el contenido del búfer lpData no está definido.

Si lpData es NULL y lpcbData no es NULL, la función devuelve ERROR_SUCCESS y almacena el tamaño de los datos, en bytes, en la variable a la que apunta lpcbData. Esto permite a una aplicación determinar la mejor manera de asignar un búfer para los datos del valor.

Si hKey especifica HKEY_PERFORMANCE_DATA y el búfer lpData no es lo suficientemente grande como para contener todos los datos devueltos, RegQueryValueEx devuelve ERROR_MORE_DATA y el valor devuelto a través del parámetro lpcbData no está definido. Esto se debe a que el tamaño de los datos de rendimiento puede cambiar de una llamada a la siguiente. En este caso, debe aumentar el tamaño del búfer y llamar a RegQueryValueEx de nuevo pasando el tamaño de búfer actualizado en el parámetro lpcbData . Repita esta acción hasta que la función se realice correctamente. Debe mantener una variable independiente para realizar un seguimiento del tamaño del búfer, ya que el valor devuelto por lpcbData es impredecible.

Si el valor del registro lpValueName no existe, RegQueryValueEx devuelve ERROR_FILE_NOT_FOUND y el valor devuelto a través del parámetro lpcbData no está definido.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es ERROR_SUCCESS.

Si se produce un error en la función, el valor devuelto es un código de error del sistema.

Si el búfer lpData es demasiado pequeño para recibir los datos, la función devuelve ERROR_MORE_DATA.

Si el valor del registro lpValueName no existe, la función devuelve ERROR_FILE_NOT_FOUND.

Comentarios

Normalmente, una aplicación llama a RegEnumValue para determinar los nombres de valor y, a continuación, RegQueryValueEx para recuperar los datos de los nombres.

Si los datos tienen el REG_SZ, REG_MULTI_SZ o REG_EXPAND_SZ tipo, es posible que la cadena no se haya almacenado con los caracteres NULL de terminación adecuados. Por lo tanto, incluso si la función devuelve ERROR_SUCCESS, la aplicación debe asegurarse de que la cadena finaliza correctamente antes de usarla; de lo contrario, puede sobrescribir un búfer. (Tenga en cuenta que REG_MULTI_SZ cadenas deben tener dos caracteres NULOs de terminación). Una manera en que una aplicación puede asegurarse de que la cadena finaliza correctamente es usar RegGetValue, que agrega caracteres nulos de terminación si es necesario.

Si los datos tienen el REG_SZ, REG_MULTI_SZ o REG_EXPAND_SZ tipo y se usa la versión ANSI de esta función (ya sea llamando explícitamente a RegQueryValueExA o no definiendo UNICODE antes de incluir el archivo Windows.h), esta función convierte la cadena Unicode almacenada en una cadena ANSI antes de copiarla en el búfer al que apunta lpData.

Al llamar a la función RegQueryValueEx con hKey establecido en el identificador de HKEY_PERFORMANCE_DATA y una cadena de valor de un objeto especificado, la estructura de datos devuelta a veces tiene objetos no requestados. No se sorprenda; este es un comportamiento normal. Al llamar a la función RegQueryValueEx , siempre debe esperar recorrer la estructura de datos devuelta para buscar el objeto solicitado.

Tenga en cuenta que las operaciones que acceden a determinadas claves del Registro se redirigen. Para obtener más información, consulte Virtualización del Registro y datos de aplicación de 32 y 64 bits en el Registro.

Ejemplos

Asegúrese de reinicializar el valor al que apunta el parámetro lpcbData cada vez que llame a esta función. Esto es muy importante cuando se llama a esta función en un bucle, como en el ejemplo de código siguiente.

#include <windows.h>
#include <malloc.h>
#include <stdio.h>

#define TOTALBYTES    8192
#define BYTEINCREMENT 4096

void main()
{
    DWORD BufferSize = TOTALBYTES;
    DWORD cbData;
    DWORD dwRet;

    PPERF_DATA_BLOCK PerfData = (PPERF_DATA_BLOCK) malloc( BufferSize );
    cbData = BufferSize;

    printf("\nRetrieving the data...");

    dwRet = RegQueryValueEx( HKEY_PERFORMANCE_DATA,
                             TEXT("Global"),
                             NULL,
                             NULL,
                             (LPBYTE) PerfData,
                             &cbData );
    while( dwRet == ERROR_MORE_DATA )
    {
        // Get a buffer that is big enough.

        BufferSize += BYTEINCREMENT;
        PerfData = (PPERF_DATA_BLOCK) realloc( PerfData, BufferSize );
        cbData = BufferSize;

        printf(".");
        dwRet = RegQueryValueEx( HKEY_PERFORMANCE_DATA,
                         TEXT("Global"),
                         NULL,
                         NULL,
                         (LPBYTE) PerfData,
                         &cbData );
    }
    if( dwRet == ERROR_SUCCESS )
        printf("\n\nFinal buffer size is %d\n", BufferSize);
    else printf("\nRegQueryValueEx failed (%d)\n", dwRet);
}

Nota

El encabezado winreg.h define RegQueryValueEx como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos


Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winreg.h (incluye Windows.h)
Library	Advapi32.lib
Archivo DLL	Advapi32.dll