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

Статья
11/20/2024

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

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

Синтаксис

STRSAFEAPI StringCchCatNA(
  [in, out] STRSAFE_LPSTR  pszDest,
  [in]      size_t         cchDest,
  [in]      STRSAFE_PCNZCH 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. Если требуется обработка значений указателя на строку NULL, см. StringCchCatNEx.

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

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

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP с пакетом обновления 2 (SP2) [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2003 с пакетом обновления 1 (SP1) [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	strsafe.h

См. также

Справочник

StringCbCatN

StringCchCat

StringCchCatNEx

Поделиться через