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

Статья
11/20/2024

Извлекает все ключи и значения для указанного раздела файла инициализации.

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

Синтаксис

DWORD GetPrivateProfileSectionW(
  [in]  LPCWSTR lpAppName,
  [out] LPWSTR  lpReturnedString,
  [in]  DWORD   nSize,
  [in]  LPCWSTR lpFileName
);

Параметры

[in] lpAppName

Имя раздела в файле инициализации.

[out] lpReturnedString

Указатель на буфер, который получает пары "имя ключа" и "значение", связанные с именованным разделом. Буфер заполняется одной или несколькими строками, завершаемых значением NULL; За последней строкой следует второй символ NULL.

[in] nSize

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

Максимальный размер раздела профиля — 32 767 символов.

[in] lpFileName

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

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

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

Замечания

Данные в буфере, на которые указывает параметр lpReturnedString, состоит из одной или нескольких строк, завершаемых значением NULL, а затем конечным символом NULL. Каждая строка имеет следующий формат:

строкиключа

Функция getPrivateProfileSection не учитывает регистр; Строка, на которую указывает параметр lpAppName, может быть сочетанием строчных и строчных букв.

Эта операция атомарна; При копировании пар "имя и значение" раздела в буфер, на который указывает параметр lpReturnedString, не допускаются обновления указанного файла инициализации.

Система сопоставляет большинство .ini ссылок на файл реестра, используя сопоставление, определенное в следующем разделе реестра:HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT 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и текст после префикса относительно этого ключа.

Комментарии (любая строка, начинающаяся с запятой), удаляются и не возвращаются в буфере lpReturnedString.

Заметка

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

Требования

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

См. также

GetPrivateProfileSectionNames

GetProfileSection

WritePrivateProfileSection

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