Функция StringCbGetsEx - это замена для функции gets. Размер, в байтах, целевого буфера передаётся в функцию, чтобы гарантировать, что StringCbGetsEx не запишет помимо конца этого буфера. Она извлекает одну строку текста из stdin, а символ перевода строки ('\n') завершает вводимые данные. Строка текста копируется в целевой буфер, а возврат каретки ('\n') заменяется нулевым символом.
Функция StringCbGetsEx добавляет к функциональным возможностям функции StringCbGets при возвращении значений - указатель на конец строки, являющейся выходным значением, а так же и число байтов, оставшееся неиспользованными в этой строке. В функцию для дополнительного управления могут также передаваться флажки.
Обратите внимание! на то, что эта функция может использоваться только в режиме inline (встраиваемом). |
HRESULT StringCbGetsEx( LPTSTR pszDest, size_t cbDest, LPTSTR *ppszDestEnd, size_t *pcbRemaining, DWORD dwFlags ); |
[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. | |
Замечания по платформе | Не имеется |