Функция SetupGetBinaryField (setupapi.h)
[Эта функция доступна для использования в операционных системах, указанных в разделе Требования. В последующих версиях он может быть изменен или недоступен. SetupAPI больше не следует использовать для установки приложений. Вместо этого используйте установщик Windows для разработки установщиков приложений. SetupAPI по-прежнему используется для установки драйверов устройств.]
Функция SetupGetBinaryField извлекает двоичные данные из строки в разделе INF-файла, от указанного поля до конца строки.
Синтаксис
WINSETUPAPI BOOL SetupGetBinaryField(
[in] PINFCONTEXT Context,
[in] DWORD FieldIndex,
[in, out] PBYTE ReturnBuffer,
[in] DWORD ReturnBufferSize,
[in, out] LPDWORD RequiredSize
);
Параметры
[in] Context
Контекст INF для строки.
[in] FieldIndex
1-й индекс начального поля в указанной строке, из которой должны быть получены двоичные данные. Двоичные данные создаются из каждого поля, начиная с этого момента до конца строки. Каждое поле соответствует 1 байту и имеет шестнадцатеричную нотацию. Значение FieldIndex с нулевым значением недопустимо для этой функции.
[in, out] ReturnBuffer
Необязательный указатель на буфер, который получает двоичные данные. Убедитесь, что целевой буфер имеет тот же размер или больше, чем исходный буфер. Вы можете вызвать функцию один раз, чтобы получить требуемый размер буфера, выделить необходимую память, а затем вызвать функцию во второй раз, чтобы получить данные. С помощью этого метода можно избежать ошибок из-за недостаточного размера буфера. См. раздел «Примечания».
[in] ReturnBufferSize
Размер буфера, на который указывает ReturnBuffer, в символах. Это число включает в себя признак конца null .
[in, out] RequiredSize
Необязательный указатель на переменную, которая получает необходимый размер буфера, указывающего на ReturnBuffer, в символах. Это число включает в себя признак конца null . Если требуемый размер больше значения, указанного параметром ReturnBufferSize, функция завершается ошибкой, и вызов GetLastError возвращает ERROR_INSUFFICIENT_BUFFER.
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение будет ненулевым.
Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.
GetLastError возвращает ERROR_INVALID_DATA, если поле, извлекаемое SetupGetBinaryField , не является допустимым шестнадцатеричным числом в диапазоне от 0 до FF.
Комментарии
Если эта функция вызывается с ReturnBufferсо значением NULL и Значением ReturnBufferSize , равным нулю, функция помещает размер буфера, необходимый для хранения указанных данных, в переменную, на которую указывает Параметр RequiredSize. Если функция выполняется успешно, возвращаемое значение будет ненулевым. В противном случае возвращаемое значение равно нулю, а расширенные сведения об ошибке можно получить, вызвав Метод GetLastError.
Чтобы лучше понять, как работает эта функция, рассмотрим следующую строку из INF-файла.
X=34,FF,00,13
Если в предыдущей строке был вызван метод SetupGetBinaryField , двоичные значения 34, FF, 00 и 13 будут помещены в буфер, заданный ReturnBuffer.
Для версии этой функции в Юникоде размеры буфера ReturnBufferSize и RequiredSize указываются в количестве символов. Это число включает в себя признак конца null . Для версии ANSI этой функции размеры указываются в количестве байтов.
Если эта функция вызывается с ReturnBufferсо значением NULL и Значением ReturnBufferSize , равным нулю, функция помещает размер буфера, необходимый для хранения указанных данных, в переменную, на которую указывает Параметр RequiredSize. Если функция выполняется успешно, возвращаемое значение будет ненулевым. В противном случае возвращаемое значение равно нулю, а расширенные сведения об ошибке можно получить, вызвав Метод GetLastError.
Таким образом, можно вызвать функцию один раз, чтобы получить требуемый размер буфера, выделить необходимую память, а затем вызвать функцию второй раз, чтобы получить данные. С помощью этого метода можно избежать ошибок из-за недостаточного размера буфера.
Требования
| Минимальная версия клиента | Windows XP [только классические приложения] |
| Минимальная версия сервера | Windows Server 2003 [только классические приложения] |
| Целевая платформа | Windows |
| Header | setupapi.h |
| Библиотека | Setupapi.lib |
| DLL | Setupapi.dll |