Функция StringCchGetsExW (strsafe.h)

Статья
11/20/2024

Возвращает одну строку текста из stdin, вплоть до и включая символ новой строки ("\n"). Строка текста копируется в целевой буфер, а новый символ заменяется пустым символом. Размер целевого буфера предоставляется функции, чтобы убедиться, что она не записывает в конец этого буфера.

примечание Эту функцию можно использовать только встраиваемой.

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

StringCchGetsEx является заменой следующих функций:

получает, _getws, _getts

StringCchGetsEx не является заменой для fgets, что не заменяет новые символы строк конечным символом NULL.

Синтаксис

STRSAFEAPI StringCchGetsExW(
  [out]           STRSAFE_LPWSTR pszDest,
  [in]            size_t         cchDest,
  [out, optional] STRSAFE_LPWSTR *ppszDestEnd,
  [out, optional] size_t         *pcchRemaining,
  [in]            DWORD          dwFlags
);

Параметры

[out] pszDest

Тип: LPTSTR

Буфер назначения, который получает скопированные символы.

[in] cchDest

Тип: size_t

Размер целевого буфера в символах. Это значение должно быть не менее 2 для успешной работы функции. Максимально допустимое число символов, включая завершающийся символ NULL, STRSAFE_MAX_CCH. Если cchDest слишком мал для хранения полной строки текста, данные усечены.

[out, optional] ppszDestEnd

Тип: LPTSTR*

Адрес указателя на конец pszDest. Если ppszDestEnd не являетсяNULL, а все данные копируются в целевой буфер, это указывает на конечный символ NULL в конце строки.

[out, optional] pcchRemaining

Тип: size_t*

Количество неиспользуемых символов в pszDest, включая завершающийся символ NULL. Если pcchRemainingNULL, количество не сохраняется или возвращается.

[in] dwFlags

Тип: DWORD

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

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

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

Тип: HRESULT

Эта функция может возвращать одно из следующих значений. Настоятельно рекомендуется использовать макросы SUCCEEDED и FAILED макросы для проверки возвращаемого значения этой функции.

Возвращаемый код	Описание
S_OK	Символы считывались из stdin, копировались в буфер в pszDest, и буфер был завершен значением NULL.
STRSAFE_E_END_OF_FILE	Указывает ошибку или условие завершения файла. Используйте feof или феррор, чтобы определить, какой из них произошел.
STRSAFE_E_INVALID_PARAMETER	Значение в cchDest больше максимального допустимого значения или недопустимого флага.
STRSAFE_E_INSUFFICIENT_BUFFER	Значение в cchDest равно 1 или меньше.

Обратите внимание, что эта функция возвращает значение HRESULT, в отличие от функций, которые он заменяет.

Замечания

StringCchGetsEx обеспечивает дополнительную обработку буферов в коде. Низкая обработка буфера связана со многими проблемами безопасности, включающими переполнение буфера. StringCchGetsEx всегда завершает буфер назначения ненулевой длины.

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

StringCchGetsEx можно использовать в универсальной форме или в более конкретных формах. Тип данных строки определяет форму этой функции, как показано в следующей таблице.

Тип данных строки	Строковый литерал	Функция
char	"string"	StringCchGetsExA
TCHAR	TEXT("string")	StringCchGetsEx
WCHAR	L"string"	StringCchGetsExW

Заметка

Заголовок strsafe.h определяет StringCchGetsEx как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP с пакетом обновления 2 (SP2) [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2003 с пакетом обновления 1 (SP1) [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	strsafe.h

См. также

Справочник

StringCbGetsEx

StringCchGets

Поделиться через