Función GetProfileStringA (winbase.h)
Recupera la cadena asociada a una clave en la sección especificada del archivo Win.ini.
Sintaxis
DWORD GetProfileStringA(
[in] LPCSTR lpAppName,
[in] LPCSTR lpKeyName,
[in] LPCSTR lpDefault,
[out] LPSTR lpReturnedString,
[in] DWORD nSize
);
Parámetros
[in] lpAppName
Nombre de la sección que contiene la clave. Si este parámetro es NULL, la función copia todos los nombres de sección del archivo en el búfer proporcionado.
[in] lpKeyName
Nombre de la clave cuya cadena asociada se va a recuperar. Si este parámetro es NULL, la función copia todas las claves de la sección especificada en el búfer proporcionado. Cada cadena va seguida de un carácter null y la cadena final va seguida de un segundo carácter null.
[in] lpDefault
Cadena predeterminada. Si no se encuentra la clave lpKeyName
Evite especificar una cadena predeterminada con caracteres en blanco finales. La función inserta un carácter null en el búfer de lpReturnedString para quitar los espacios en blanco finales.
[out] lpReturnedString
Puntero a un búfer que recibe la cadena de caracteres.
[in] nSize
Tamaño del búfer al que apunta el parámetro lpReturnedString, en caracteres.
Valor devuelto
El valor devuelto es el número de caracteres copiados en el búfer, sin incluir el carácter nulo-terminating.
Si ni lpAppName ni lpKeyName es null y el búfer de destino proporcionado es demasiado pequeño para contener la cadena solicitada, la cadena se trunca y va seguida de un carácter NULL y el valor devuelto es igual a nSize menos uno.
Si lpAppName o lpKeyName es NULL y el búfer de destino proporcionado es demasiado pequeño para contener todas las cadenas, la última cadena se trunca y va seguida de dos caracteres null. En este caso, el valor devuelto es igual a nSize menos dos.
Observaciones
Si la cadena asociada a la
La función
Una sección del archivo Win.ini debe tener el siguiente formato:
[section]
key=string
.
.
.
Una aplicación puede usar la función
El parámetro lpDefault debe apuntar a una cadena válida, incluso si la cadena está vacía (es decir, aunque su primer carácter sea un carácter null).
Windows Server 2003 y Windows XP/2000: las llamadas a funciones de perfil se pueden asignar al registro en lugar de a los archivos de inicialización. Esta asignación se produce cuando se especifica el archivo de inicialización y la sección en el Registro en las claves siguientes:
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\IniFileMapping
Cuando se ha asignado la operación, la función GetProfileString recupera información del Registro, no del archivo de inicialización; el cambio en la ubicación de almacenamiento no tiene ningún efecto en el comportamiento de la función.
Las funciones de perfil usan los pasos siguientes para localizar la información de inicialización:
- Busque en el Registro el nombre del archivo de inicialización en la clave IniFileMapping.
- Busque el nombre de sección especificado por lpAppName. Este será un valor con nombre bajo la clave que tiene el nombre del archivo de inicialización, o una subclave con este nombre, o bien el nombre no existirá como un valor o una subclave.
- Si el nombre de sección especificado por lpAppName es un valor con nombre, ese valor especifica dónde en el Registro encontrará las claves de la sección.
- Si el nombre de sección especificado por lpAppName es una subclave, los valores con nombre de esa subclave especifican dónde encontrará las claves de la sección. Si la clave que busca no existe como un valor con nombre, habrá un valor sin nombre (que se muestra como <Sin nombre>) que especifica la ubicación predeterminada en el Registro donde encontrará la clave.
- Si el nombre de sección especificado por lpAppName no existe como un valor con nombre o como una subclave, habrá un valor sin nombre (que se muestra como <Sin nombre>) que especifica la ubicación predeterminada en el Registro donde encontrará las claves de la sección.
- Si no hay ninguna subclave o entrada para el nombre de la sección, busque el archivo de inicialización real en el disco y lea su contenido.
- ! : este carácter obliga a todas las escrituras a ir al registro y al archivo .ini en el disco.
- # : este carácter hace que el valor del Registro se establezca en el valor en el archivo de .ini de Windows 3.1 cuando un nuevo usuario inicie sesión por primera vez después de la instalación.
- @ : este carácter impide que las lecturas vayan al archivo .ini en el disco si los datos solicitados no se encuentran en el registro.
- USR: : este prefijo significa HKEY_CURRENT_USERy el texto después del prefijo es relativo a esa clave.
- SYS: : este prefijo significa HKEY_LOCAL_MACHINE\SOFTWAREy el texto después del prefijo es relativo a esa clave.
Nota
El encabezado winbase.h define GetProfileString 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 |
winbase.h (incluya Windows.h) |
| biblioteca de |
Kernel32.lib |
| DLL de |
Kernel32.dll |