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