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

Статья
03/05/2024

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

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

Синтаксис

STRSAFEAPI StringCchCatNW(
  [in, out] STRSAFE_LPWSTR  pszDest,
  [in]      size_t          cchDest,
  [in]      STRSAFE_PCNZWCH pszSrc,
  [in]      size_t          cchToAppend
);

Параметры

[in, out] pszDest

Тип: LPTSTR

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

[in] cchDest

Тип: size_t

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

[in] pszSrc

Тип: LPCTSTR

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

[in] cchToAppend

Тип: size_t

Максимальное число символов, добавляемых в pszDest.

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

Тип: HRESULT

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

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

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

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

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

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

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

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

Примечание

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

Требования

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

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

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

StringCbCatN

StringCchCat

StringCchCatNEx