Функция SetupGetLineTextA (setupapi.h)

Статья
11/20/2024

[Эта функция доступна для использования в операционных системах, указанных в разделе "Требования". Он может быть изменен или недоступен в последующих версиях. SetupAPI больше не следует использовать для установки приложений. Вместо этого используйте установщик Windows для разработки установщиков приложений. SetupAPI по-прежнему используется для установки драйверов устройств.]

Функция setupGetLine Text возвращает содержимое строки в INF-файле в компактной форме. Извлекаемая строка может быть указана структурой INFCONTEXT, возвращаемой из функции SetupFindLineXXXX, или путем явной передачи в дескриптор INF, раздел и ключ требуемой строки.

Синтаксис

WINSETUPAPI BOOL SetupGetLineTextA(
  [in]      PINFCONTEXT Context,
  [in]      HINF        InfHandle,
  [in]      PCSTR       Section,
  [in]      PCSTR       Key,
  [in, out] PSTR        ReturnBuffer,
  [in]      DWORD       ReturnBufferSize,
  [in, out] PDWORD      RequiredSize
);

Параметры

[in] Context

Контекст строки в INF-файле, текст которого требуется извлечь. Этот параметр может быть NULL. Если контекстNULL, InfHandle, раздел и ключ должны быть указаны.

[in] InfHandle

Обрабатывайте ЗАПРОС к INF-файлу. Этот параметр может быть NULL. Этот параметр используется только в том случае, если контекстаNULL. Если контекстNULL, InfHandle, раздел и ключ должны быть указаны.

[in] Section

Указатель на строку,null-terminated, указывающую раздел, содержащий имя ключа строки, текст которой требуется извлечь. Этот параметр может быть NULL. Этот параметр используется только в том случае, если контекстаNULL. Если контекст имеет значение NULL, InfHandle, Sectionи Key необходимо указать.

[in] Key

Указатель на строку null-terminated, которая содержит имя ключа, связанная строка которого требуется извлечь. Этот параметр может быть NULL. Этот параметр используется только в том случае, если контекстаNULL. Если контекст имеет значение NULL, InfHandle, Sectionи Key необходимо указать.

[in, out] ReturnBuffer

Если не значение NULL, ReturnBuffer указывает на буфер, в котором эта функция возвращает содержимое строки. Строка null-terminated не должна превышать размер целевого буфера. Вы можете вызвать функцию один раз, чтобы получить необходимый размер буфера, выделить необходимую память, а затем вызвать функцию во второй раз, чтобы получить данные. С помощью этого метода можно избежать ошибок из-за недостаточного размера буфера. См. раздел "Примечания". Этот параметр может быть NULL.

[in] ReturnBufferSize

Размер буфера, на который указывает параметр ReturnBuffer, в символах. Это включает в себя null конца.

[in, out] RequiredSize

Если не значение NULL, указывает на переменную, в которой эта функция возвращает требуемый размер буфера, на который указывает параметр ReturnBuffer, в символах. Это включает в себя null конца. Если указан ReturnBuffer, а требуемый размер превышает значение, указанное в параметре ReturnBufferSize, функция завершается ошибкой и не сохраняет данные в буфере.

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

Если функция выполнена успешно, возвращаемое значение является ненулевое значение.

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

Замечания

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

Эта функция возвращает содержимое строки в компактном формате. Все ненужные пробелы удаляются, а многострочные значения преобразуются в одну непрерывную строку. Например, эта строка:

HKLM, , PointerClass0, 1 \
; This is a comment
01, 02, 03

возвращается следующим образом:

HKLM,,PointerClass0,1,01,02,03

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2003 [только классические приложения]
целевая платформа	Виндоус
заголовка	setupapi.h
библиотеки	Setupapi.lib
DLL	Setupapi.dll
набор API	ext-ms-win-setupapi-inf-l1-1-0 (представлено в Windows 8)