Функция StringCbGetsA (strsafe.h)

Статья
11/20/2024

Возвращает одну строку текста из stdin, вплоть до и включая символ новой строки ("\n"). Строка текста копируется в целевой буфер, а новый символ заменяется пустым символом. Размер целевого буфера предоставляется функции, чтобы убедиться, что она не записывает в конец этого буфера.

примечание Эту функцию можно использовать только встраиваемой.

StringCbGets является заменой следующих функций:

получает, _getws, _getts

StringCbGets не является заменой fgets, что не заменяет новые строки символами конца null.

Синтаксис

STRSAFEAPI StringCbGetsA(
  [out] STRSAFE_LPSTR pszDest,
  [in]  size_t        cbDest
);

Параметры

[out] pszDest

Тип: LPTSTR

Целевой буфер, который получает входные данные.

[in] cbDest

Тип: size_t

Размер целевого буфера в байтах. Это значение должно быть больше sizeof(TCHAR) для успешной работы функции. Максимально допустимое число байтов — STRSAFE_MAX_CCH * sizeof(TCHAR). Если cbDest слишком мал для хранения полной строки текста, данные усечены.

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

Тип: HRESULT

Эта функция может возвращать одно из следующих значений. Настоятельно рекомендуется использовать макросы SUCCEEDED и FAILED макросы для проверки возвращаемого значения этой функции.

Возвращаемый код	Описание
S_OK	Данные считывались из stdin, копировались в буфер по pszDest, а буфер был завершен с пустым завершением.
STRSAFE_E_END_OF_FILE	Указывает ошибку или условие завершения файла. Используйте feof или феррор, чтобы определить, какой из них произошел.
STRSAFE_E_INVALID_PARAMETER	Значение в cbDest больше максимального допустимого значения.
STRSAFE_E_INSUFFICIENT_BUFFER	Значение в cbDest`sizeof(TCHAR)` или меньше.

Обратите внимание, что эта функция возвращает значение HRESULT, в отличие от функций, которые он заменяет.

Замечания

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

Значение pszDest не должно быть NULL. Если требуется обработка значений указателя строки null, см. StringCbGetsEx.

StringCbGets можно использовать в универсальной форме или в более конкретных формах. Тип данных строки определяет форму этой функции, как показано в следующей таблице.

Тип данных строки	Строковый литерал	Функция
char	"string"	StringCbGetsA
TCHAR	TEXT("string")	StringCbGets
WCHAR	L"string"	StringCbGetsW

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP с пакетом обновления 2 (SP2) [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2003 с пакетом обновления 1 (SP1) [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	strsafe.h

См. также

Справочник

StringCbGetsEx

StringCchGets

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