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

  • Статья

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

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

Синтаксис

STRSAFEAPI StringCchCatA(
  [in, out] STRSAFE_LPSTR  pszDest,
  [in]      size_t         cchDest,
  [in]      STRSAFE_LPCSTR pszSrc
);

Параметры

[in, out] pszDest

Тип: LPTSTR

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

[in] cchDest

Тип: size_t

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

[in] pszSrc

Тип: LPCTSTR

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

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

Тип: HRESULT

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

Код возврата Описание
S_OK
 Исходные данные присутствовали, строки были полностью сцеплены без усечения, а результирующий буфер назначения завершается null.
STRSAFE_E_INVALID_PARAMETER
 Значение в cchDest равно 0 или больше STRSAFE_MAX_CCH либо целевой буфер уже заполнен.
STRSAFE_E_INSUFFICIENT_BUFFER
 Операция объединения завершилась сбоем из-за нехватки буферного пространства. Целевой буфер содержит усеченную версию предполагаемого результата, завершаемую null. В ситуациях, когда усечение приемлемо, это не обязательно может рассматриваться как условие сбоя.
 

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

Комментарии

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

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

Ни pszSrc, ни pszDest не должны иметь значение NULL. См . раздел StringCchCatEx , если требуется обработка значений строкового указателя null.

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

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

Примечание

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

Требования

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

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

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

StringCbCat

StringCchCatEx

StringCchCatN