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

  • Статья

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

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

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

StringCbGetsEx не является заменой fgets, которая не заменяет символы новой строки завершающим символом NULL.

Синтаксис

STRSAFEAPI StringCbGetsExW(
  [out]           STRSAFE_LPWSTR pszDest,
  [in]            size_t         cbDest,
  [out, optional] STRSAFE_LPWSTR *ppszDestEnd,
  [out, optional] size_t         *pcbRemaining,
  [in]            DWORD          dwFlags
);

Параметры

[out] pszDest

Тип: LPTSTR

Буфер назначения, который будет принимать входные данные.

[in] cbDest

Тип: size_t

Размер буфера назначения в байтах. Для успешного выполнения функции это значение должно быть больше sizeof(TCHAR) . Максимально допустимое число байтов — STRSAFE_MAX_CCH * sizeof(TCHAR). Если cbDest слишком мал для хранения полной строки текста, данные усекаются.

[out, optional] ppszDestEnd

Тип: LPTSTR*

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

[out, optional] pcbRemaining

Тип: size_t*

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

[in] dwFlags

Тип: DWORD

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

Значение Значение
STRSAFE_FILL_BEHIND_NULL
0x00000200
 Если функция выполняется успешно, низкий байт dwFlags (0) используется для заполнения неинициализированной части pszDest после завершающего символа NULL.
STRSAFE_IGNORE_NULLS
0x00000100
 Обрабатываются пустые строки указателей NULL (TEXT("")). Этот флаг полезен для эмуляции таких функций, как lstrcpy.
STRSAFE_FILL_ON_FAILURE
0x00000400
 Если функция завершается ошибкой, для заполнения всего буфера pszDest используется низкий байт dwFlags (0), а буфер завершается значением 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 или ferror , чтобы определить, какой из них произошел.
STRSAFE_E_INVALID_PARAMETER
 Значение в cbDest больше, чем максимально допустимое значение, или был передан недопустимый флаг.
STRSAFE_E_INSUFFICIENT_BUFFER
 Значение в cbDest равно 1 или меньше.
 

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

Комментарии

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

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

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

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

Примечание

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

Требования

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

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

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

StringCbGets

StringCchGetsEx