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

Извлекает строку, связанную с ключом в указанном разделе файла Win.ini.

Синтаксис

DWORD GetProfileStringA(
  [in]  LPCSTR lpAppName,
  [in]  LPCSTR lpKeyName,
  [in]  LPCSTR lpDefault,
  [out] LPSTR  lpReturnedString,
  [in]  DWORD  nSize
);

Параметры

[in] lpAppName

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

[in] lpKeyName

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

[in] lpDefault

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

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

[out] lpReturnedString

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

[in] nSize

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

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

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

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

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

Комментарии

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

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

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

[section]
key=string
      .
      .
      .

Приложение может использовать функцию GetPrivateProfileString для получения строки из указанного файла инициализации.

Параметр lpDefault должен указывать на допустимую строку, даже если строка пуста (то есть даже если ее первый символ является пустым ).

Windows Server 2003 и Windows XP/2000: Вызовы функций профиля могут быть сопоставлены с реестром, а не с файлами инициализации. Это сопоставление возникает, когда файл и раздел инициализации указаны в реестре в следующих разделах:

HKEY_LOCAL_MACHINE\Программного обеспечения\Microsoft\\ Windows NT CurrentVersion\IniFileMapping

После сопоставления операции функция GetProfileString извлекает сведения из реестра, а не из файла инициализации; Изменение расположения хранилища не влияет на поведение функции.

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

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

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

Требования

См. также

GetPrivateProfileString

WriteProfileString