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

Статья
11/20/2024

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

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

Синтаксис

DWORD GetPrivateProfileStringW(
  [in]  LPCWSTR lpAppName,
  [in]  LPCWSTR lpKeyName,
  [in]  LPCWSTR lpDefault,
  [out] LPWSTR  lpReturnedString,
  [in]  DWORD   nSize,
  [in]  LPCWSTR lpFileName
);

Параметры

[in] lpAppName

Имя раздела, содержащего имя ключа. Если этот параметр равен NULL, функция getPrivateProfileStr ing копирует все имена разделов в файл в предоставленный буфер.

[in] lpKeyName

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

[in] lpDefault

Строка по умолчанию. Если ключ lpKeyName не найден в файле инициализации, GetPrivateProfileString копирует строку по умолчанию в буфер lpReturnedString.

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

Избегайте указания строки по умолчанию с конечными пустыми символами. Функция вставляет символ null в буфер lpReturnedString, чтобы удалить все конечные пробелы.

[out] lpReturnedString

Указатель на буфер, получающий полученную строку.

[in] nSize

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

[in] lpFileName

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

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

Возвращаемое значение — это число символов, скопированных в буфер, не включая завершающийся символ null.

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

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

В случае, если файл инициализации, указанный lpFileName, не найден или содержит недопустимые значения, эта функция устанавливает ошибку со значением "0x2" (Файл не найден). Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.

Замечания

Функция getPrivateProfileString выполняет поиск указанного файла инициализации ключа, соответствующего имени, заданному параметром lpKeyName в заголовке раздела, указанном параметром lpAppName. Если он находит ключ, функция копирует соответствующую строку в буфер. Если ключ не существует, функция копирует строку символов по умолчанию, указанную параметром lpDefault. Раздел в файле инициализации должен иметь следующую форму:

[section]
key=string
      .
      .
      .

Если lpAppNameNULL, GetPrivateProfileString копирует все имена разделов в указанном файле в указанный буфер. Если lpKeyNameNULL, функция копирует все имена ключей в указанном разделе в предоставленный буфер. Приложение может использовать этот метод для перечисления всех разделов и ключей в файле. В любом случае каждая строка следует за символом null, а за последней строкой следует второй null символ. Если предоставленный буфер назначения слишком мал, чтобы сохранить все строки, последняя строка усечена и за ним следует два пустых символов.

Если строка, связанная с lpKeyName заключена в одинарные или двойные кавычки, метки удаляются при получении строки GetPrivateProfileString.

Функция GetPrivateProfileString не учитывает регистр; Строки могут быть сочетанием прописных и строчных букв.

Чтобы получить строку из файла Win.ini, используйте функцию GetProfileString.

Система сопоставляет большинство .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и текст после префикса относительно этого ключа.

Пример

В следующем примере показано использование GetPrivateProfileString.

// Gets a profile string called "Preferred line" and converts it to an int.
GetPrivateProfileString (
      "Preference",
      "Preferred Line",
      gszNULL, 
      szBuffer,
      MAXBUFSIZE,
      gszINIfilename
);

// if szBuffer is not empty.
if ( lstrcmp ( gszNULL, szBuffer ) )
{
      dwPreferredPLID = (DWORD) atoi( szBuffer );	
}
else	
{
      dwPreferredPLID = (DWORD) -1;
}

Заметка

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

Требования

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

См. также

GetProfileString

WritePrivateProfileString

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