Функция StringCbGetsEx

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

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

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

Синтаксис

HRESULT StringCbGetsEx(      

    LPTSTR pszDest,
    size_t cbDest,
    LPTSTR *ppszDestEnd,
    size_t *pcbRemaining,
    DWORD dwFlags
);

Параметры

pszDest

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

cbDest

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

ppszDestEnd

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

pcbRemaining

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

dwFlags

[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 для проверки возвращаемого значения этой функцией.

 

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

Описание

S_OK Данные были прочитаны из stdin, скопированы в буфер определенный pszDest, а буфер был завершен символом конца строки ('\0').
STRSAFE_E_END_OF_FILE Указывает на условие метки конца файла или ошибку. Используйте функцию feof или ferror, чтобы установить, что произошло.
STRSAFE_E_INVALID_PARAMETER Значение в cbDest больше, чем максимально возможное значение или передан недопустимый флажок.
STRSAFE_E_INSUFFICIENT_BUFFER Значение в cbDest равно 1 или меньше.

Замечания

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

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

Тип данных строки

Литерал строки

Функция

char "string" StringCbGetsExA
TCHAR TEXT("string") StringCbGetsEx
WCHAR L"string" StringCbGetsExW

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

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

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

Смотри также

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

Размещение и совместимость StringCbGetsEx

К Windows XP Да
л Windows 2000 Professional Да
и Windows NT Workstation Да версии 3.1
е Windows Me Да
н Windows 98 Да
т Windows 95 Да
 
С Windows Server 2003 Да
е Windows 2000 Server Да
р Windows NT Server Да версии 3.1
в    
е    
р    
Используемая библиотека -
Используемая DLL -
Заголовочный файл  
- объявлено в strsafe.h
- включено в -
Unicode Реализуются как версии Unicode и ANSI.
Замечания по платформе Не имеется

 

Назад в оглавление
На главную страницу
В оглавление справки

Hosted by uCoz