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

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

  • Статья

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

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

Синтаксис

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, по умолчанию используется пустая строка "".

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

[out] lpReturnedString

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

[in] nSize

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

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

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

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

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

Замечания

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

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

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

[section]
key=string
      .
      .
      .

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

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

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

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\IniFileMapping

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

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

  1. Найдите в реестре имя файла инициализации в ключа IniFileMapping.
  2. Найдите имя раздела, указанное lpAppName. Это будет именованное значение под ключом, которое имеет имя файла инициализации, или подраздел с этим именем, или имя не будет существовать как значение или вложенный ключ.
  3. Если имя раздела, указанное lpAppName является именованным значением, то это значение указывает, где в реестре будут находиться ключи для раздела.
  4. Если имя раздела, указанное lpAppName является вложенным ключом, то именованные значения в этом подразделе указывают, где в реестре будут находиться ключи для раздела. Если ключ, который вы ищете, не существует в качестве именованного значения, то будет неименованное значение (показано как <No Name>), указывающее расположение по умолчанию в реестре, где будет находиться ключ.
  5. Если имя раздела, указанное lpAppName, не существует в качестве именованного значения или в качестве подраздела, то будет неименованное значение (показано как <no Name>), указывающее расположение по умолчанию в реестре, где будут находиться ключи раздела.
  6. Если для имени раздела нет подраздела или записи, найдите фактический файл инициализации на диске и считывает его содержимое.
При просмотре значений в реестре, определяющих другие расположения реестра, существует несколько префиксов, которые изменяют поведение сопоставления файлов .ini:
  • ! — этот символ заставляет все записи переходить как в реестр, так и в файл .ini на диске.
  • # — этот символ приводит к тому, что значение реестра должно быть задано в файле Windows 3.1 .ini при первом входе пользователя в систему.
  • @ — этот символ запрещает чтение в файл .ini на диске, если запрошенные данные не найдены в реестре.
  • USR: — этот префикс обозначает HKEY_CURRENT_USER, а текст после префикса относительно этого ключа.
  • SYS: — этот префикс обозначает HKEY_LOCAL_MACHINE\SOFTWAREи текст после префикса относительно этого ключа.

Заметка

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

Требования

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

См. также

GetPrivateProfileString

WriteProfileString