Обратите внимание! на то, что эта функция может использоваться только
в режиме inline (встраиваемом).Функция StringCbGets - это замена для функции gets. Размер, в байтах, целевого буфера передается в функцию, чтобы гарантировать, что StringCbGets не запишет помимо конца этого буфера. Функция извлекает одну строку текста из stdin, символ перевода строки ('\n') завершает вводимые данные. Строка текста копируется в целевой буфер, а возврат каретки ('\n') заменяется нулевым символом.
| Обратите внимание! на то, что эта функция может использоваться только
в режиме inline (встраиваемом). |
HRESULT StringCbGets( LPTSTR pszDest, size_t cbDest ); |
[out] Указатель на буфер, который получает вводимые данные.
cbDest[in] Размер целевого буфера, в байтах. Это значение для функции должно быть больше чем sizeof (TCHAR), чтобы она завершила успешно работу. Максимальное допустимое число байтов является STRSAFE_MAX_CCH * sizeof (TCHAR). Если cbDest является слишком маленьким, чтобы содержать полную строку текста, данные обрезаются.
| Обратите внимание! на то, что функция возвращает значение
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 - sizeof (TCHAR) или меньше. |
Функция StringCbGets предусматривает дополнительную обработку для корректной обработки буфера в вашем коде. Плохая обработка буфера влечет за собой многие проблемы обеспечения безопасности, которые вызывают переполнение буфера. StringCbGets всегда завершает символом конца строки ('\0') целевой буфер ненулевой длины.
Функция StringCbGets может быть использована в своей унифицированной форме, или специально как StringCbGetsA (для строк ANSI) или StringCbGetsW (для строк Unicode). Форма использования определяется вашими данными.
Тип данных строки |
Литерал строки |
Функция |
|---|---|---|
| char | "string" | StringCbGetsA |
| TCHAR | TEXT("string") | StringCbGets |
| WCHAR | L"string" | StringCbGetsW |
Функция StringCbGets и её варианты ANSI и Unicode - заменяет эти функции:
Функция StringCbGets не заменяет функцию fgets. Эта функция не заменяет символы новой строки символом завершающего нуля.
Значение pszDest не должно быть NULL. См. описание StringCbGetsEx, если потребуется обработка значений указателя пустой строки.
Обзор Строки, Функции, используемые строками, StringCchGets, StringCbGetsEx
|
Размещение и совместимость StringCbGets |
||
| К | 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. | |
| Замечания по платформе | Не имеется | |
