Функция 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, за которым следует последний символ NULL . Каждая строка имеет следующую форму:
Ключ=Строка
Функция WritePrivateProfileSection не учитывает регистр; Строка, на которую указывает параметр lpAppName , может быть сочетанием прописных и строчных букв.
Если имя раздела не совпадает со строкой, на которую указывает параметр 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 , является подразделом, то именованные значения в этом подразделе укажите, где в реестре будут находиться ключи для раздела. Если ключ, который вы ищете, не существует как именованное значение, будет неименованное значение (отображается как <Без имени>), указывающее расположение по умолчанию в реестре, где будет находиться ключ.
- Если имя раздела, указанное в параметре lpAppName , не существует в качестве именованного значения или подраздела, будет указано неименованное значение (без <имени>), указывающее расположение по умолчанию в реестре, где будут находиться ключи для раздела.
- Если для имени раздела нет подраздела или записи, найдите фактический файл инициализации на диске и прочитайте его содержимое.
- ! — этот символ заставляет все операции записи отправляться как в реестр, так и в файл .ini на диске.
- # — этот символ приводит к тому, что для параметра реестра будет задано значение в файле .ini Windows 3.1, когда новый пользователь впервые входит в систему после установки.
- @ — этот символ не позволяет выполнять операции чтения в .ini файл на диске, если запрошенные данные не найдены в реестре.
- USR: этот префикс означает HKEY_CURRENT_USER, а текст после префикса относится к этому ключу.
- SYS: этот префикс означает HKEY_LOCAL_MACHINE\SOFTWARE, а текст после префикса относится к этому ключу.
Примечание
Заголовок winbase.h определяет WritePrivateProfileSection в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 2000 Professional [только классические приложения] |
| Минимальная версия сервера | Windows 2000 Server [только классические приложения] |
| Целевая платформа | Windows |
| Header | winbase.h (включая Windows.h) |
| Библиотека | Kernel32.lib |
| DLL | Kernel32.dll |