Función RegQueryValueExA (winreg.h)
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 sea terminado en null. Use la función RegGetValue si desea asegurarse de que los valores de cadena devueltos están terminados en null. A continuación encontrará más información.
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 claves del Registro.
Este identificador lo devuelve el RegCreateKeyEx, RegCreateKeyTransacted, RegOpenKeyExo función 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, consulte 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, consulte Tipos de valor del Registro. El parámetro lpType puede ser NULL si no se requiere el código de tipo.
[out, optional] lpData
Puntero a un búfer que recibe los datos del valor. Este parámetro puede ser null si no se necesitan los datos.
[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 la función devuelve, esta variable contiene el tamaño de los datos copiados en lpData.
El parámetro lpcbData de
Si los datos tienen el tipo REG_SZ, REG_MULTI_SZ o REG_EXPAND_SZ, este tamaño incluye cualquier terminación carácter o caracteres nulos a menos que los datos se almacenen sin ellos. Para obtener más información, vea Comentarios.
Si el búfer especificado por 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 de lpData no está definido.
Si lpData es NULL y lpcbData no esNULL, 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 de 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 pasar de nuevo el tamaño de búfer actualizado en el parámetro lpcbData. Repita esto 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
Valor devuelto
Si la función se ejecuta correctamente, se ERROR_SUCCESS el valor devuelto.
Si se produce un error en la función, el valor devuelto es un código de error del sistema .
Si el búfer de lpData es demasiado pequeño para recibir los datos, la función devuelve ERROR_MORE_DATA.
Si el lpValueName valor del Registro no existe, la función devuelve ERROR_FILE_NOT_FOUND.
Observaciones
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 tipo REG_SZ, REG_MULTI_SZ o REG_EXPAND_SZ, es posible que la cadena no se haya almacenado con los caracteres de nulos correctos. 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 las cadenas de REG_MULTI_SZ deben tener dos caracteres de nulos). Una manera en que una aplicación puede asegurarse de que la cadena está terminada correctamente es usar RegGetValue, que agrega terminación caracteres null si es necesario.
Si los datos tienen el tipo REG_SZ, REG_MULTI_SZ o REG_EXPAND_SZ, 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 consultados. 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, vea de 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 dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| cliente mínimo admitido | Windows 2000 Professional [solo aplicaciones de escritorio] |
| servidor mínimo admitido | Windows 2000 Server [solo aplicaciones de escritorio] |
| de la plataforma de destino de |
Windows |
| encabezado de |
winreg.h (incluya Windows.h) |
| biblioteca de |
Advapi32.lib |
| DLL de |
Advapi32.dll |
Consulte también
RegQueryInfoKey de
de información general del Registro de