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

Статья
11/20/2024

Копирует данные в ключ в указанном разделе файла инициализации. При копировании данных функция вычисляет контрольную сумму и добавляет ее в конец данных. Функция 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.

Замечания

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

[section]
key=string
      .
      .
      .

Если параметр 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 является вложенным ключом, то именованные значения в этом подразделе указывают, где в реестре будут находиться ключи для раздела. Если ключ, который вы ищете, не существует в качестве именованного значения, то будет неименованное значение (показано как <No Name>), указывающее расположение по умолчанию в реестре, где будет находиться ключ.
Если имя раздела, указанное lpAppName, не существует в качестве именованного значения или в качестве подраздела, то будет неименованное значение (показано как <no Name>), указывающее расположение по умолчанию в реестре, где будут находиться ключи раздела.
Если для имени раздела нет подраздела или записи, найдите фактический файл инициализации на диске и считывает его содержимое.

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

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

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	winbase.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll

См. также

GetPrivateProfileString

WriteProfileString

Поделиться через