Функция WritePrivateProfileStringA (winbase.h)
Копирует строку в указанный раздел файла инициализации.
Синтаксис
BOOL WritePrivateProfileStringA(
[in] LPCSTR lpAppName,
[in] LPCSTR lpKeyName,
[in] LPCSTR lpString,
[in] LPCSTR lpFileName
);
Параметры
[in] lpAppName
Имя раздела, в который будет скопирована строка. Если раздел не существует, он создается. Имя раздела является независимым от регистра; Строка может быть любой комбинацией прописных и строчных букв.
[in] lpKeyName
Имя ключа, связанного со строкой. Если ключ не существует в указанном разделе, он создается. Если этот параметр значение NULL, удаляется весь раздел, включая все записи в разделе.
[in] lpString
Строка null-terminated, которая записывается в файл. Если этот параметр значение 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. В этом случае функция записывает сведения в реестр, а не в файл инициализации; Изменение расположения хранилища не влияет на поведение функции.
Функции профиля используют следующие действия для поиска сведений о инициализации:
- Найдите в реестре имя файла инициализации в
ключа IniFileMapping. - Найдите имя раздела, указанное lpAppName. Это будет именованное значение под ключом, которое имеет имя файла инициализации, или подраздел с этим именем, или имя не будет существовать как значение или вложенный ключ.
- Если имя раздела, указанное lpAppName является именованным значением, то это значение указывает, где в реестре будут находиться ключи для раздела.
- Если имя раздела, указанное lpAppName является вложенным ключом, то именованные значения в этом подразделе указывают, где в реестре будут находиться ключи для раздела. Если ключ, который вы ищете, не существует в качестве именованного значения, то будет неименованное значение (показано как <No Name>), указывающее расположение по умолчанию в реестре, где будет находиться ключ.
- Если имя раздела, указанное lpAppName, не существует в качестве именованного значения или в качестве подраздела, то будет неименованное значение (показано как <no Name>), указывающее расположение по умолчанию в реестре, где будут находиться ключи раздела.
- Если для имени раздела нет подраздела или записи, найдите фактический файл инициализации на диске и считывает его содержимое.
- ! — этот символ заставляет все записи переходить как в реестр, так и в файл .ini на диске.
- # — этот символ приводит к тому, что значение реестра должно быть задано в файле Windows 3.1 .ini при первом входе пользователя в систему.
- @ — этот символ запрещает чтение в файл .ini на диске, если запрошенные данные не найдены в реестре.
- USR: — этот префикс обозначает HKEY_CURRENT_USER, а текст после префикса относительно этого ключа.
- SYS: — этот префикс обозначает HKEY_LOCAL_MACHINE\SOFTWAREи текст после префикса относительно этого ключа.
- Убедитесь, что в системе нет файла .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 Профессиональный [только классические приложения] |
| минимальный поддерживаемый сервер | Windows 2000 Server [только классические приложения] |
| целевая платформа | Виндоус |
| заголовка | winbase.h (включая Windows.h) |
| библиотеки |
Kernel32.lib |
| DLL | Kernel32.dll |