Функция WritePrivateProfileSectionA (winbase.h)
Заменяет ключи и значения для указанного раздела в файле инициализации.
Синтаксис
BOOL WritePrivateProfileSectionA(
[in] LPCSTR lpAppName,
[in] LPCSTR lpString,
[in] LPCSTR lpFileName
);
Параметры
[in] lpAppName
Имя раздела, в котором записываются данные. Обычно это имя вызывающего приложения.
[in] lpString
Новые имена ключей и связанные значения, которые записываются в именованный раздел. Эта строка ограничена 65 535 байтами.
[in] lpFileName
Имя файла инициализации. Если этот параметр не содержит полный путь к файлу, функция выполняет поиск в каталоге Windows для файла. Если файл не существует и lpFileName не содержит полный путь, функция создает файл в каталоге Windows.
Если файл существует и был создан с помощью символов Юникода, функция записывает символы Юникода в файл. В противном случае функция создает файл с помощью символов ANSI.
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение ненулевое.
Если функция завершается ошибкой, возвращаемое значение равно нулю. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.
Замечания
Данные в буфере, на которые указывает параметр lpString, состоит из одной или нескольких строк null-terminated, а затем окончательного null символа. Каждая строка имеет следующую форму:
Функция WritePrivateProfileSection
Если имя раздела не совпадает со строкой, указанной параметром lpAppName, WritePrivateProfileSection создает раздел в конце указанного файла инициализации нового раздела с указанными парами имен ключей и значений.
WritePrivateProfileSection удаляет существующие ключи и значения именованного раздела и вставляет имена ключей и значения в буфер, на которые указывает параметр lpString. Функция не пытается сопоставить старые и новые имена ключей; Если новые имена отображаются в другом порядке от старых имен, все примечания, связанные с предварительными ключами и значениями в файле инициализации, вероятно, будут связаны с неправильными ключами и значениями.
Эта операция атомарна; Операции, которые считываются из указанного файла инициализации или записываются в указанный файл инициализации, не допускаются во время записи сведений.
Система сохраняет кэшированную версию последнего сопоставления файлов реестра для повышения производительности. Если все параметры 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и текст после префикса относительно этого ключа.
Заметка
Заголовок winbase.h определяет WritePrivateProfileSection как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Windows 2000 Профессиональный [только классические приложения] |
| минимальный поддерживаемый сервер | Windows 2000 Server [только классические приложения] |
| целевая платформа | Виндоус |
| заголовка | winbase.h (включая Windows.h) |
| библиотеки |
Kernel32.lib |
| DLL | Kernel32.dll |