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

  • Статья

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

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

[in] lpKeyName

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

[in] lpDefault

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

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

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

[out] lpReturnedString

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

[in] nSize

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

[in] lpFileName

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

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

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

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

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

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

Комментарии

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

[section]
key=string
      .
      .
      .

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

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

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

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

Система сопоставляет большинство .ini ссылок на файлы с реестром, используя сопоставление, определенное в следующем разделе реестра:HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\IniFileMapping

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

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

  1. Найдите в реестре имя файла инициализации в разделе IniFileMapping .
  2. Найдите имя раздела, указанное в параметре lpAppName. Это будет именованное значение в ключе, которое имеет имя файла инициализации, или подраздел с этим именем, или имя не будет существовать как значение или подраздел.
  3. Если имя раздела, указанное lpAppName , является именованным значением, то это значение указывает, где в реестре будут находиться ключи для раздела.
  4. Если имя раздела, указанное в lpAppName , является подразделом, то именованные значения в этом подразделе укажите, где в реестре будут находиться ключи для раздела. Если ключ, который вы ищете, не существует как именованное значение, будет неименованное значение (отображается как <Без имени>), указывающее расположение по умолчанию в реестре, где будет находиться ключ.
  5. Если имя раздела, указанное в параметре lpAppName , не существует в качестве именованного значения или подраздела, будет указано неименованное значение (без <имени>), указывающее расположение по умолчанию в реестре, где будут находиться ключи для раздела.
  6. Если для имени раздела нет подраздела или записи, найдите фактический файл инициализации на диске и прочитайте его содержимое.
При просмотре значений в реестре, указывающих другие расположения реестра, существует несколько префиксов, которые изменяют поведение сопоставления файлов .ini:
  • ! — этот символ заставляет все операции записи отправляться как в реестр, так и в файл .ini на диске.
  • # — этот символ приводит к тому, что для параметра реестра будет задано значение в файле .ini Windows 3.1, когда новый пользователь впервые входит в систему после установки.
  • @ — этот символ не позволяет выполнять операции чтения в .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 или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

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

См. также

GetProfileString

WritePrivateProfileString