Функция RtlStringCchCatNA (ntstrsafe.h)

Функции RtlStringCchCatNW и RtlStringCchCatNA объединяют две строки с подсчетом символов, ограничивая размер добавленной строки.

Синтаксис

NTSTRSAFEDDI RtlStringCchCatNA(
  [in, out] NTSTRSAFE_PSTR pszDest,
  [in]      size_t         cchDest,
  [in]      STRSAFE_PCNZCH pszSrc,
            size_t         cchToAppend
);

Параметры

[in, out] pszDest

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

[in] cchDest

Размер буфера назначения в символах. Максимально допустимое количество символов — NTSTRSAFE_MAX_CCH.

[in] pszSrc

Указатель на строку, завершаемую null. Эта строка будет сцеплена с концом строки, содержащейся в буфере в pszDest.

cchToAppend

Максимальное число символов, добавляемых к строке, содержащейся в буфере в pszDest.

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

Функция возвращает одно из значений NTSTATUS, перечисленных в следующей таблице. Сведения о проверке значений NTSTATUS см. в разделе Использование значений NTSTATUS.

Код возврата	Описание
STATUS_SUCCESS	Это состояние успешного выполнения означает, что исходные данные присутствовали, строки были сцеплены без усечения, а результирующий целевой буфер завершается со значением NULL.
STATUS_BUFFER_OVERFLOW	Это состояние предупреждения означает, что операция объединения не завершена из-за нехватки буферного пространства. Целевой буфер содержит усеченную версию предполагаемого результата, завершаемую null.
STATUS_INVALID_PARAMETER	Это состояние ошибки означает, что функция получила недопустимый входной параметр. Дополнительные сведения см. в следующем абзаце. Функция возвращает значение STATUS_INVALID_PARAMETER в следующих случаях: Значение в cchDest больше максимального размера буфера. Целевой буфер уже заполнен. Существовал указатель NULL . Длина целевого буфера равна нулю, но при этом присутствовала строка источника ненулевой длины.

Комментарии

Вместо следующих функций следует использовать RtlStringCchCatNW и RtlStringCchCatNA:

• strncat
• wcsncat

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

Используйте RtlStringCchCatNW для обработки строк Юникода и RtlStringCchCatNA для обработки строк ANSI. Используемая форма зависит от данных, как показано в следующей таблице.

Строковый тип данных	Строковый литерал	Функция
WCHAR	L"string"	RtlStringCchCatNW
Char	Строка	RtlStringCchCatNA

 

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

Ни pszSrc, ни pszDest не могут иметь значение NULL. Если необходимо обрабатывать значения строкового указателя NULL, используйте RtlStringCchCatNEx.

Дополнительные сведения о безопасных строковых функциях см. в разделе Использование безопасных строковых функций.

Требования

Требование	Значение
Минимальная версия клиента	Доступно в Windows XP с пакетом обновления 1 (SP1) и более поздних версиях Windows.
Целевая платформа	Персональный компьютер
Верхняя часть	ntstrsafe.h (включая Ntstrsafe.h)
Библиотека	Ntstrsafe.lib
IRQL	Любое значение, если строки, которыми осуществляется управление, всегда находятся в памяти, в противном случае PASSIVE_LEVEL

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

RtlStringCbCatN

RtlStringCchCat

RtlStringCchCatNEx