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

Статья
02/07/2025

RtlStringCbCatW и RtlStringCbCatA функции объединяют две байтовые строки.

Синтаксис

NTSTRSAFEDDI RtlStringCbCatA(
  [in, out] NTSTRSAFE_PSTR  pszDest,
  [in]      size_t          cbDest,
  [in]      NTSTRSAFE_PCSTR pszSrc
);

Параметры

[in, out] pszDest

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

[in] cbDest

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

Для строк Юникода максимальное число байтов равно NTSTRSAFE_MAX_CCH * sizeof(WCHAR).

Для строк ANSI максимальное число байтов равно NTSTRSAFE_MAX_CCH * sizeof(char).

[in] pszSrc

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

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

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

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

Возвращаемый код

Описание

STATUS_SUCCESS

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

STATUS_BUFFER_OVERFLOW

Это предупреждение состояние означает, что операция объединения не завершена из-за нехватки буферного пространства. Целевой буфер содержит усеченную, завершаемую null версию предполагаемого результата.

STATUS_INVALID_PARAMETER

Это ошибка состоянии означает, что функция получила недопустимый входной параметр. Дополнительные сведения см. в следующем абзаце.

Возвращаемое значение STATUS_INVALID_PARAMETER означает, что произошло одно из следующих действий:

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

Замечания

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

strcat
wcscat

Так как RtlStringCbCatW и RtlStringCbCatA получать размер буфера назначения в качестве входных данных, они не записываются в конце буфера.

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

Тип строковых данных	Строковый литерал	Функция
WCHAR	L"string"	RtlStringCbCatW
char	"string"	RtlStringCbCatA

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

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

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

Требования

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

См. также

RtlStringCbCatEx

RtlStringCbCatNEx

RtlStringCchCatEx

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