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

Сцепляет одну строку с другой. Размер буфера назначения предоставляется функции, чтобы гарантировать, что она не будет записывать данные после конца этого буфера.

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

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

• strcat, wcscat, _tcsat
• lstrcat
• StrCat
• StrCatBuff

Синтаксис

STRSAFEAPI StringCchCatExA(
  [in, out]       STRSAFE_LPSTR  pszDest,
  [in]            size_t         cchDest,
  [in]            STRSAFE_LPCSTR pszSrc,
  [out, optional] STRSAFE_LPSTR  *ppszDestEnd,
  [out, optional] size_t         *pcchRemaining,
  [in]            DWORD          dwFlags
);

Параметры

[in, out] pszDest

Тип: LPTSTR

Буфер назначения, который содержит строку, которая должна быть сцеплена с pszSrc и которая получит всю результирующую строку. Строка в pszSrc добавляется в конец строки в pszDest.

[in] cchDest

Тип: size_t

Размер буфера назначения в символах. Это значение должно равняться длине pszSrc плюс длина pszDest плюс 1, чтобы учитывать обе строки и завершающий символ NULL. Максимально допустимое количество символов — STRSAFE_MAX_CCH.

[in] pszSrc

Тип: LPCTSTR

Исходная строка, которая должна быть сцеплена с концом pszDest. Эта строка должна заканчиваться null.

[out, optional] ppszDestEnd

Тип: LPTSTR*

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

[out, optional] pcchRemaining

Тип: size_t*

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

[in] dwFlags

Тип: DWORD

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

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

Тип: HRESULT

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

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

Комментарии

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

Поведение не определено, если строки, на которые указывают pszSrc и pszDest , перекрываются.

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

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

Требования

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

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

StringCbCatEx

StringCchCat

StringCchCatNEx