Función WritePrivateProfileStringA (winbase.h)
Copia una cadena en la sección especificada de un archivo de inicialización.
Sintaxis
BOOL WritePrivateProfileStringA(
[in] LPCSTR lpAppName,
[in] LPCSTR lpKeyName,
[in] LPCSTR lpString,
[in] LPCSTR lpFileName
);
Parámetros
[in] lpAppName
Nombre de la sección a la que se copiará la cadena. Si la sección no existe, se creará. El nombre de la sección es independiente de mayúsculas y minúsculas; la cadena puede ser cualquier combinación de letras mayúsculas y minúsculas.
[in] lpKeyName
Nombre de la clave que se va a asociar a una cadena. Si la clave no existe en la sección especificada, se crea. Si este parámetro es NULL, se elimina toda la sección, incluidas todas las entradas de la sección.
[in] lpString
Cadena terminada en null que se va a escribir en el archivo. Si este parámetro es NULL, se elimina la clave a la que apunta el parámetro lpKeyName .
[in] lpFileName
Nombre del archivo de inicialización.
Si el archivo se creó con caracteres Unicode, la función escribe caracteres Unicode en el archivo. De lo contrario, la función escribe caracteres ANSI.
Valor devuelto
Si la función copia correctamente la cadena en el archivo de inicialización, el valor devuelto es distinto de cero.
Si se produce un error en la función o si vacía la versión almacenada en caché del archivo de inicialización al que se ha accedido más recientemente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.
Comentarios
Una sección del archivo de inicialización debe tener el siguiente formato:
[section]
key=string
.
.
.
Si el parámetro lpFileName no contiene una ruta de acceso completa y un nombre de archivo para el archivo, WritePrivateProfileString busca en el directorio de Windows el archivo. Si el archivo no existe, esta función crea el archivo en el directorio de Windows.
Si lpFileName contiene una ruta de acceso completa y un nombre de archivo y el archivo no existe, WritePrivateProfileString crea el archivo. El directorio especificado ya debe existir.
El sistema mantiene una versión almacenada en caché de la asignación de archivos del Registro más reciente para mejorar el rendimiento. Si todos los parámetros son NULL, la función vacía la memoria caché. Mientras el sistema edita la versión almacenada en caché del archivo, los procesos que editan el propio archivo usarán el archivo original hasta que se haya borrado la memoria caché.
El sistema asigna la mayoría de .ini referencias de archivo al Registro, mediante la asignación definida en la siguiente clave del Registro:
HKEY_LOCAL_MACHINE SOFTWARE Microsoft Windows NT CurrentVersion IniFileMapping
Esta asignación es probable si una aplicación modifica los archivos de inicialización del componente del sistema, como Control.ini, System.ini y Winfile.ini. En este caso, la función escribe información en el Registro, no en el 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 buscar 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. Se trata de 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 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 en el registro encontrará las claves de la sección. Si la clave que está buscando no existe como un valor con nombre, habrá un valor sin nombre (mostrado como <Sin nombre>) que especifique 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 (mostrado como <Sin nombre>) que especifique 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 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 tanto al Registro como al archivo .ini en el disco.
- # : este carácter hace que el valor del Registro se establezca en el valor del archivo de .ini de Windows 3.1 cuando un nuevo usuario inicia 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_USER y 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.
- Asegúrese de que no existe ningún archivo .ini del nombre especificado en el sistema.
- Asegúrese de que hay una entrada de clave en el Registro que especifica el archivo .ini. Esta entrada debe estar en la ruta de accesoHKEY_LOCAL_MACHINE\SOFTWARE \Microsoft\Windows NT\CurrentVersion\IniFileMapping.
- Especifique un valor para esa entrada de clave de archivo .ini que especifique una sección. Es decir, una aplicación debe especificar un nombre de sección, ya que aparecería dentro de un archivo o entrada del Registro de .ini. Este es un ejemplo: [Mi sección].
- En el caso de los archivos del sistema, especifique SYS para un valor agregado.
- En el caso de los archivos de aplicación, especifique USR dentro del valor agregado. Este es un ejemplo: "Mi sección: USR: Nombre de la aplicación\Sección". Además, dado que USR indica una asignación en HKEY_CURRENT_USER, la aplicación también debe crear una clave en HKEY_CURRENT_USER que especifique el nombre de la aplicación que aparece en el valor agregado. En el ejemplo que se acaba de dar, sería "Nombre de la aplicación".
- Después de seguir los pasos anteriores, un programa de instalación de la aplicación debe llamar a WritePrivateProfileString con los tres primeros parámetros establecidos en NULL y el cuarto parámetro establecido en el nombre de archivo INI. Por ejemplo:
WritePrivateProfileString( NULL, NULL, NULL, L"appname.ini" ); - Esta llamada hace que la asignación de un archivo .ini al Registro surte efecto antes del siguiente reinicio del sistema. El sistema vuelve a leer la información de asignación en la memoria compartida. Un usuario no tendrá que reiniciar su equipo después de instalar una aplicación para que las invocaciones futuras de la aplicación vean la asignación del archivo .ini al registro.
Ejemplos
El código de ejemplo siguiente ilustra las instrucciones anteriores y se basa en varias suposiciones:
- Hay una aplicación denominada Nombre de aplicación.
- Esa aplicación usa un archivo .ini denominado AppName.ini.
- Hay una sección en el archivo .ini que queremos tener este aspecto:
[Section1] FirstKey = It all worked out okay. SecondKey = By golly, it works. ThirdKey = Another test. - El usuario no tendrá que reiniciar el sistema para que futuras invocaciones de la aplicación vean la asignación del archivo .ini al registro.
#include <windows.h>
#include <tchar.h>
#include <stdio.h>
int main()
{
TCHAR inBuf[80];
HKEY hKey1, hKey2;
DWORD dwDisposition;
LONG lRetCode;
TCHAR szData[] = TEXT("USR:App Name\\Section1");
// Create the .ini file key.
lRetCode = RegCreateKeyEx ( HKEY_LOCAL_MACHINE,
TEXT("SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\IniFileMapping\\appname.ini"),
0,
NULL,
REG_OPTION_NON_VOLATILE,
KEY_WRITE,
NULL,
&hKey1,
&dwDisposition);
if (lRetCode != ERROR_SUCCESS)
{
printf ("Error in creating appname.ini key (%d).\n", lRetCode);
return (0) ;
}
// Set a section value
lRetCode = RegSetValueEx ( hKey1,
TEXT("Section1"),
0,
REG_SZ,
(BYTE *)szData,
sizeof(szData));
if (lRetCode != ERROR_SUCCESS)
{
printf ("Error in setting Section1 value\n");
// Close the key
lRetCode = RegCloseKey( hKey1 );
if( lRetCode != ERROR_SUCCESS )
{
printf("Error in RegCloseKey (%d).\n", lRetCode);
return (0) ;
}
}
// Create an App Name key
lRetCode = RegCreateKeyEx ( HKEY_CURRENT_USER,
TEXT("App Name"),
0,
NULL,
REG_OPTION_NON_VOLATILE,
KEY_WRITE,
NULL,
&hKey2,
&dwDisposition);
if (lRetCode != ERROR_SUCCESS)
{
printf ("Error in creating App Name key (%d).\n", lRetCode);
// Close the key
lRetCode = RegCloseKey( hKey2 );
if( lRetCode != ERROR_SUCCESS )
{
printf("Error in RegCloseKey (%d).\n", lRetCode);
return (0) ;
}
}
// Force the system to read the mapping into shared memory
// so that future invocations of the application will see it
// without the user having to reboot the system
WritePrivateProfileStringW( NULL, NULL, NULL, L"appname.ini" );
// Write some added values
WritePrivateProfileString (TEXT("Section1"),
TEXT("FirstKey"),
TEXT("It all worked out OK."),
TEXT("appname.ini"));
WritePrivateProfileString (TEXT("Section1"),
TEXT("SecondKey"),
TEXT("By golly, it works!"),
TEXT("appname.ini"));
WritePrivateProfileString (TEXT("Section1"),
TEXT("ThirdKey"),
TEXT("Another test..."),
TEXT("appname.ini"));
// Test
GetPrivateProfileString (TEXT("Section1"),
TEXT("FirstKey"),
TEXT("Error: GPPS failed"),
inBuf,
80,
TEXT("appname.ini"));
_tprintf (TEXT("Key: %s\n"), inBuf);
// Close the keys
lRetCode = RegCloseKey( hKey1 );
if( lRetCode != ERROR_SUCCESS )
{
printf("Error in RegCloseKey (%d).\n", lRetCode);
return(0);
}
lRetCode = RegCloseKey( hKey2 );
if( lRetCode != ERROR_SUCCESS )
{
printf("Error in RegCloseKey (%d).\n", lRetCode);
return(0);
}
return(1);
}
Nota
El encabezado winbase.h define WritePrivateProfileString 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 neutro 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
| Requisito | Value |
|---|---|
| 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 | winbase.h (incluya Windows.h) |
| Library | Kernel32.lib |
| Archivo DLL | Kernel32.dll |