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

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

  • Статья

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

Примечание Эту функцию можно использовать только в встроенном коде.
 
StringCchGets является заменой следующих функций: StringCchGets не является заменой fgets, которая не заменяет символы новой строки завершающим символом NULL.

Синтаксис

STRSAFEAPI StringCchGetsW(
  [out] STRSAFE_LPWSTR pszDest,
  [in]  size_t         cchDest
);

Параметры

[out] pszDest

Тип: LPTSTR

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

[in] cchDest

Тип: size_t

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

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

Тип: HRESULT

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

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

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

Комментарии

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

Значение pszDest не должно иметь значение NULL. Если требуется обработка значений указателя null, см. раздел StringCchGetsEx .

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

Тип данных String Строковый литерал Функция
char Строка StringCchGetsA
TCHAR TEXT("string") StringCchGets
WCHAR L"string" StringCchGetsW
 

Примечание

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

Требования

Требование Значение
Минимальная версия клиента Windows XP с пакетом обновления 2 (SP2) [классические приложения | Приложения UWP]
Минимальная версия сервера Windows Server 2003 с пакетом обновления 1 (SP1) [классические приложения | Приложения UWP]
Целевая платформа Windows
Header strsafe.h

См. также раздел

Справочные материалы

StringCbGets

StringCchGetsEx