Функция StringCbGetsEx

Функция StringCbGetsEx - это замена для функции gets. Размер, в байтах, целевого буфера передаётся в функцию, чтобы гарантировать, что StringCbGetsEx не запишет помимо конца этого буфера. Она извлекает одну строку текста из stdin, а символ перевода строки ('\n') завершает вводимые данные. Строка текста копируется в целевой буфер, а возврат каретки ('\n') заменяется нулевым символом.

Функция StringCbGetsEx добавляет к функциональным возможностям функции StringCbGets при возвращении значений - указатель на конец строки, являющейся выходным значением, а так же и число байтов, оставшееся неиспользованными в этой строке. В функцию для дополнительного управления могут также передаваться флажки.

Обратите внимание! на то, что эта функция может использоваться только в режиме inline (встраиваемом).

Синтаксис

Параметры

[out] Указатель на буфер, который получает вводимые данные.

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

[out] Адрес указателя на конец pszDest. Если ppszDestEnd не-NULL, и любые данные копируются в целевой буфер, то он указывает на символ завершающего нуля в конце строки.

[out] Указатель на переменную, которая указывает число неиспользованных байтов в pszDest, включая и те, которые используется для символа завершающего нуля. Если pcbRemaining - NULL, подсчет не сохраняется или возвращается значение.  

[in] Одно или несколько из нижеследующих значений.

Значение	Предназначение
STRSAFE_FILL_BEHIND_NULL	Если функция завершается успешно, младший байт параметра dwFlags (0) используется, чтобы заполнить неинициализированную часть pszDest после символа завершающего нуля.
STRSAFE_IGNORE_NULLS	Обрабатывает указатели пустой строки подобно пустым строкам ( TEXT ("")). Этот флажок полезен для эмуляции такой функции как lstrcpy.
STRSAFE_FILL_ON_FAILURE	Если функция завершается ошибкой, младший байт dwFlags (0) используется, чтобы заполнить весь буфер pszDest и буфер завершается символом конца строки ('\0'). В случае сбоя типа STRSAFE_E_INSUFFICIENT_BUFFER,  поверх записывается возвращенная обрезанная строка.
STRSAFE_NULL_ON_FAILURE	Если функция завершается ошибкой, параметр pszDest устанавливается в пустую строку ( TEXT ("")). В случае сбоя STRSAFE_E_INSUFFICIENT_BUFFER,  поверх записывается  обрезанная строка.
STRSAFE_NO_TRUNCATION	Как и в случае STRSAFE_NULL_ON_FAILURE, если функция завершается ошибкой, pszDest устанавливается в пустую строку ( TEXT ("")). В случае сбоя типа STRSAFE_E_INSUFFICIENT_BUFFER поверх записывается обрезанная строка.

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

Обратите внимание! на то, что функция возвращает значение HRESULT в противоположность функции gets, которая возвращает указатель. Поэтому настоятельно рекомендуется, чтобы вы использовали макросы SUCCEEDED и FAILED для проверки возвращаемого значения этой функцией.

Замечания

Функция StringCbGetsEx предусматривает дополнительную обработку для правильной работы буфера в вашем коде. Плохая обработка буфера влечет за собой многие проблемы обеспечения безопасности, которые вызывают переполнение буфера. StringCbGetsEx всегда завершает символом конца строки ('\0') целевой буфер ненулевой длины.

Функция StringCbGetsEx может быть использована в своей унифицированной форме, или специально как  StringCbGetsExA (для строк ANSI) или StringCbGetsExW (для строк Unicode). Форма использования определяется вашими данными.

Функция StringCbGetsEx и её варианты ANSI и Unicode - заменяет эти функции:

• gets
• _getws
• _getts

Функция StringCbGetsEx не заменяет функцию fgets. Эта функция не заменяет символы новой строки символом завершающего нуля.

Значение pszDest не должно быть NULL, если не определяется флажок STRSAFE_IGNORE_NULLS. Однако, ошибка из-за недостаточного пространства буфера может все еще возвратиться даже при том, что игнорируются пустые значения.

Смотри также

Обзор Строки, Функции, используемые строками,  StringCchGetsEx, StringCbGets