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

Статья
08/27/2023

Копирует данные в ключ в указанном разделе файла инициализации. При копировании данных функция вычисляет контрольную сумму и добавляет ее в конец данных. Функция GetPrivateProfileStruct использует контрольную сумму для обеспечения целостности данных.

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

Синтаксис

BOOL WritePrivateProfileStructA(
  [in] LPCSTR lpszSection,
  [in] LPCSTR lpszKey,
  [in] LPVOID lpStruct,
  [in] UINT   uSizeStruct,
  [in] LPCSTR szFile
);

Параметры

[in] lpszSection

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

[in] lpszKey

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

[in] lpStruct

Копируемые данные. Если этот параметр имеет значение NULL, ключ удаляется.

[in] uSizeStruct

Размер буфера, на который указывает параметр lpStruct , в байтах.

[in] szFile

Имя файла инициализации. Если этот параметр имеет значение NULL, данные копируются в файл Win.ini.

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

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

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

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

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

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

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

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

HKEY_LOCAL_MACHINE
   SOFTWARE
      Microsoft
         Windows NT
            CurrentVersion
               IniFileMapping

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

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

Найдите в реестре имя файла инициализации в разделе IniFileMapping .
Найдите имя раздела, указанное в параметре lpAppName. Это будет именованное значение в ключе, которое имеет имя файла инициализации, или подраздел с этим именем, или имя не будет существовать как значение или подраздел.
Если имя раздела, указанное lpAppName , является именованным значением, то это значение указывает, где в реестре будут находиться ключи для раздела.
Если имя раздела, указанное в lpAppName , является подразделом, то именованные значения в этом подразделе укажите, где в реестре будут находиться ключи для раздела. Если ключ, который вы ищете, не существует как именованное значение, будет неименованное значение (отображается как <Без имени>), указывающее расположение по умолчанию в реестре, где будет находиться ключ.
Если имя раздела, указанное в параметре lpAppName , не существует в качестве именованного значения или подраздела, будет указано неименованное значение (без <имени>), указывающее расположение по умолчанию в реестре, где будут находиться ключи для раздела.
Если для имени раздела нет подраздела или записи, найдите фактический файл инициализации на диске и прочитайте его содержимое.

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

! — этот символ заставляет все операции записи отправляться как в реестр, так и в файл .ini на диске.
# — этот символ приводит к тому, что для параметра реестра будет задано значение в файле .ini Windows 3.1, когда новый пользователь впервые входит в систему после установки.
@ — этот символ не позволяет выполнять операции чтения в .ini файл на диске, если запрошенные данные не найдены в реестре.
USR: этот префикс означает HKEY_CURRENT_USER, а текст после префикса относится к этому ключу.
SYS: этот префикс означает HKEY_LOCAL_MACHINE\SOFTWARE, а текст после префикса относится к этому ключу.

Примечание

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

Требования

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

См. также

GetPrivateProfileString

WriteProfileString