Функция SetupGetStringFieldW (setupapi.h)
[Эта функция доступна для использования в операционных системах, указанных в разделе Требования. В последующих версиях он может быть изменен или недоступен. SetupAPI больше не следует использовать для установки приложений. Вместо этого используйте установщик Windows для разработки установщиков приложений. SetupAPI по-прежнему используется для установки драйверов устройств.]
Функция SetupGetStringField извлекает строку из указанного поля строки в INF-файле.
Синтаксис
WINSETUPAPI BOOL SetupGetStringFieldW(
[in] PINFCONTEXT Context,
[in] DWORD FieldIndex,
[in, out] PWSTR ReturnBuffer,
[in] DWORD ReturnBufferSize,
[out] PDWORD RequiredSize
);
Параметры
[in] Context
Указатель на контекст строки в INF-файле.
[in] FieldIndex
Индекс поля в заданной строке, из которой должна быть извлечена строка, на основе 1. Используйте FieldIndex со значением 0, чтобы получить строковый ключ, если он имеется.
[in, out] ReturnBuffer
Необязательный указатель на буфер, который получает строку, завершающуюся null. Убедитесь, что целевой буфер имеет тот же размер или больше, чем исходный буфер. Этот параметр может принимать значение NULL. См. раздел «Примечания».
[in] ReturnBufferSize
Размер буфера, на который указывает ReturnBuffer, в символах. Сюда входит признак конца null .
[out] RequiredSize
Необязательный указатель на переменную, которая получает требуемый размер буфера, на который указывает параметр ReturnBuffer , в символах. Если указан параметр ReturnBuffer и фактический требуемый размер превышает значение, указанное в параметре ReturnBufferSize, функция завершается ошибкой и не сохраняет строку в буфере. В этом случае вызов GetLastError возвращает ERROR_INSUFFICIENT_BUFFER. Для версии этой функции в Юникоде требуется размер в символах. Сюда входит признак конца null .
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение будет ненулевым.
Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.
Комментарии
Если эта функция вызывается с ReturnBufferсо значением NULL и Значением ReturnBufferSize , равным нулю, функция помещает размер буфера, необходимый для хранения указанных данных, в переменную, на которую указывает Параметр RequiredSize. Если функция выполняется успешно, возвращаемое значение будет ненулевым. В противном случае возвращаемое значение равно нулю, а расширенные сведения об ошибке можно получить, вызвав Метод GetLastError.
Вы можете вызвать функцию один раз, чтобы получить требуемый размер буфера, выделить необходимую память, а затем вызвать функцию во второй раз, чтобы получить данные. С помощью этого метода можно избежать ошибок из-за недостаточного размера буфера.
Обратите внимание, что максимальная длина любой отдельной строки, указанной в разделе Inf Strings, составляет 512 символов, включая завершающее значение NULL. Если длина строки превышает 512, она будет усечена и ошибка не будет возвращена. Максимальная длина любой сцепленной строки, созданной из одного или нескольких токенов %strkey%, составляет 4096 символов.
Примечание
Заголовок setupapi.h определяет SetupGetStringField в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Минимальная версия клиента | Windows XP [только классические приложения] |
| Минимальная версия сервера | Windows Server 2003 [только классические приложения] |
| Целевая платформа | Windows |
| Header | setupapi.h |
| Библиотека | Setupapi.lib |
| DLL | Setupapi.dll |
| Набор API | ext-ms-win-setupapi-inf-l1-1-1 (представлено в Windows 10 версии 10.0.14393) |