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

Статья
08/26/2023

Определяет, превышает ли строка указанную длину в символах.

StringCchLength заменяет следующие функции:

strlen, wcslen, _tcslen

Синтаксис

STRSAFEAPI StringCchLengthA(
  [in]  STRSAFE_PCNZCH psz,
  [in]  size_t         cchMax,
  [out] size_t         *pcchLength
);

Параметры

[in] psz

Тип: LPCTSTR

Строка, длина которой должна быть проверена.

[in] cchMax

Тип: size_t

Максимальное число символов, допустимое в psz, включая завершающий символ NULL. Это значение не может превышать STRSAFE_MAX_CCH.

[out] pcchLength

Тип: size_t*

Количество символов в psz, не включая завершающий символ NULL. Это значение допустимо только в том случае, если pcch не равно NULL и функция завершается успешно.

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

Тип: HRESULT

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

Код возврата	Описание
S_OK	Строка в psz не была NULL, а длина строки (включая завершающий символ NULL) меньше или равна символам cchMax .
STRSAFE_E_INVALID_PARAMETER	Значение в psz равно NULL, cchMax больше STRSAFE_MAX_CCH или psz длиннее cchMax.

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

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

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

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

UnalignedStringCchLength является псевдонимом для этой функции.

Примечание

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

Требования

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

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

StringCbLength