Функция WritePrivateProfileStringA (winbase.h)

  • Статья

Копирует строку в указанный раздел файла инициализации.

Примечание Эта функция предоставляется только для совместимости с 16-разрядными версиями Windows. Приложения должны хранить сведения об инициализации в реестре.
 

Синтаксис

BOOL WritePrivateProfileStringA(
  [in] LPCSTR lpAppName,
  [in] LPCSTR lpKeyName,
  [in] LPCSTR lpString,
  [in] LPCSTR lpFileName
);

Параметры

[in] lpAppName

Имя раздела, в который будет скопирована строка. Если раздел не существует, он создается. Имя раздела не зависит от регистра; Строка может быть любым сочетанием прописных и строчных букв.

[in] lpKeyName

Имя ключа, связанного со строкой. Если ключ не существует в указанном разделе, он создается. Если этот параметр имеет значение NULL, весь раздел, включая все записи в разделе, удаляется.

[in] lpString

Строка, завершающаяся нулевым значением, для записи в файл. Если этот параметр имеет значение NULL, ключ, на который указывает параметр lpKeyName , удаляется.

[in] lpFileName

Имя файла инициализации.

Если файл был создан с использованием символов Юникода, функция записывает в файл символы Юникода. В противном случае функция записывает символы ANSI.

Возвращаемое значение

Если функция успешно копирует строку в файл инициализации, возвращаемое значение не равно нулю.

Если функция завершается сбоем или она сбрасывает кэшированную версию последнего файла инициализации, возвращаемое значение равно нулю. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Комментарии

Раздел в файле инициализации должен иметь следующую форму:

[section]
key=string
      .
      .
      .

Если параметр lpFileName не содержит полный путь и имя файла, WritePrivateProfileString выполняет поиск файла в каталоге Windows. Если файл не существует, эта функция создает файл в каталоге Windows.

Если lpFileName содержит полный путь и имя файла, а файл не существует, writePrivateProfileString создает файл. Указанный каталог уже должен существовать.

Система сохраняет кэшированную версию последнего сопоставления файлов реестра для повышения производительности. Если все параметры имеют значение NULL, функция очищает кэш. Пока система редактирует кэшированную версию файла, процессы, которые редактируют сам файл, будут использовать исходный файл до тех пор, пока кэш не будет очищен.

Система сопоставляет большинство .ini ссылок на файлы с реестром, используя сопоставление, определенное в следующем разделе реестра:

HKEY_LOCAL_MACHINE
   SOFTWARE
      Microsoft
         Windows NT
            CurrentVersion
               IniFileMapping

Это сопоставление вероятно, если приложение изменяет файлы инициализации системных компонентов, такие как Control.ini, System.ini и Winfile.ini. В этом случае функция записывает сведения в реестр, а не в файл инициализации; Изменение расположения хранилища не влияет на поведение функции.

Функции профиля используют следующие действия для поиска сведений об инициализации.

  1. Найдите в реестре имя файла инициализации в разделе IniFileMapping .
  2. Найдите имя раздела, указанное в параметре lpAppName. Это будет именованное значение в ключе, которое имеет имя файла инициализации, или подраздел с этим именем, или имя не будет существовать в качестве значения или подраздела.
  3. Если имя раздела, указанное в параметре lpAppName , является именованным значением, то это значение указывает, где в реестре будут находиться разделы для раздела.
  4. Если имя раздела, указанное в параметре lpAppName , является подразделом, то именованные значения под этим подразделом указывают, где в реестре будут находиться ключи для раздела. Если ключ, который вы ищете, не существует как именованное значение, то будет неименованное значение (отображается как <Без имени>), указывающее расположение по умолчанию в реестре, где будет находиться ключ.
  5. Если имя раздела, указанное в параметре lpAppName , не существует в качестве именованного значения или подраздела, будет указано неименованное значение (без <имени>), указывающее расположение по умолчанию в реестре, где будут находиться ключи для раздела.
  6. Если для имени раздела нет подраздела или записи, найдите фактический файл инициализации на диске и считайте его содержимое.
При просмотре значений в реестре, указывающих другие расположения реестра, существует несколько префиксов, которые изменяют поведение сопоставления файлов .ini:
  • ! — этот символ заставляет все операции записи идти как в реестр, так и в файл .ini на диске.
  • # — этот символ определяет значение реестра в файле .ini Windows 3.1 при первом входе нового пользователя после установки.
  • @ — этот символ предотвращает любые операции чтения в файл .ini на диске, если запрошенные данные не найдены в реестре.
  • USR: этот префикс означает HKEY_CURRENT_USER, а текст после префикса находится относительно этого ключа.
  • SYS: этот префикс означает HKEY_LOCAL_MACHINE\SOFTWARE, а текст после префикса находится относительно этого ключа.
Приложение, использующее функцию WritePrivateProfileString для ввода .ini сведений о файле в реестр, должно следовать следующим рекомендациям:
  • Убедитесь, что в системе нет файла .ini с указанным именем.
  • Убедитесь, что в реестре есть запись раздела, указывающая файл .ini. Эта запись должна находиться в пути HKEY_LOCAL_MACHINE\SOFTWARE \Microsoft\Windows NT\CurrentVersion\IniFileMapping.
  • Укажите значение для .ini записи ключа файла, указывающей раздел. Это значит, что приложение должно указать имя раздела, которое будет отображаться в .ini файле или записи реестра. Ниже приведен пример: [Мой раздел].
  • Для системных файлов укажите SYS в качестве дополнительного значения.
  • Для файлов приложения укажите USR в добавленном значении. Ниже приведен пример: "My Section: USR: App Name\Section". Так как USR указывает сопоставление в HKEY_CURRENT_USER, приложение также должно создать ключ в HKEY_CURRENT_USER , указывающий имя приложения, указанное в добавленном значении. В приведенном примере это будет "Имя приложения".
  • После выполнения предыдущих шагов программа установки приложения должна вызвать WritePrivateProfileString с первыми тремя параметрами, имеющими значение NULL, а четвертый — именем INI-файла. Пример:

    WritePrivateProfileString( NULL, NULL, NULL, L"appname.ini" );

  • Такой вызов приводит к тому, что сопоставление файла .ini с реестром вступит в силу перед следующей перезагрузкой системы. Система повторно считывает сведения о сопоставлении в общую память. Пользователю не придется перезагружать компьютер после установки приложения, чтобы будущие вызовы приложения видели сопоставление файла .ini с реестром.

Примеры

Следующий пример кода иллюстрирует предыдущие рекомендации и основан на нескольких предположениях:

  • Существует приложение с именем Имя приложения.
  • Это приложение использует файл .ini с именем AppName.ini.
  • В файле .ini есть раздел, который мы хотим выглядеть следующим образом:
    [Section1] 
  FirstKey = It all worked out okay. 
  SecondKey = By golly, it works. 
  ThirdKey = Another test.
  • Пользователю не придется перезагружать систему, чтобы будущие вызовы приложения видели сопоставление файла .ini с реестром.
#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); 
}

Примечание

Заголовок winbase.h определяет WritePrivateProfileString в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование Значение
Минимальная версия клиента Windows 2000 Professional [только классические приложения]
Минимальная версия сервера Windows 2000 Server [только классические приложения]
Целевая платформа Windows
Header winbase.h (включая Windows.h)
Библиотека Kernel32.lib
DLL Kernel32.dll

См. также

GetPrivateProfileString

WriteProfileString