Compartir a través de


Función WritePrivateProfileStringA (winbase.h)

Copia una cadena en la sección especificada de un archivo de inicialización.

Nota Esta función solo se proporciona para la compatibilidad con versiones de 16 bits de Windows. Las aplicaciones deben almacenar información de inicialización en el Registro.
 

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:

  1. Busque en el Registro el nombre del archivo de inicialización en la clave IniFileMapping .
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
Al examinar los valores del registro que especifican otras ubicaciones del Registro, hay varios prefijos que cambian el comportamiento de la asignación de archivos .ini:
  • ! : 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.
Una aplicación que use la función WritePrivateProfileString para escribir .ini información de archivo en el registro debe seguir estas instrucciones:
  • 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

Vea también

GetPrivateProfileString

WriteProfileString