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

Статья
02/07/2025

Функция RtlUnicodeStringCbCatN объединяет две строки, содержащиеся в UNICODE_STRING структурах при ограничении размера скопированной строки.

Синтаксис

NTSTRSAFEDDI RtlUnicodeStringCbCatN(
  [in, out] PUNICODE_STRING  DestinationString,
  [in]      PCUNICODE_STRING SourceString,
  [in]      size_t           cbToAppend
);

Параметры

[in, out] DestinationString

Указатель на структуру UNICODE_STRING. Эта структура включает в себя буфер, содержащий целевую строку, к которой будет объединена исходная строка. В выходных данных этот буфер является целевым буфером, который содержит всю результирующую строку. Исходная строка добавляется в конец конечной строки. Максимальное количество байтов в строковом буфере структуры — NTSTRSAFE_UNICODE_STRING_MAX_CCH * sizeof(WCHAR).

[in] SourceString

Указатель на структуру UNICODE_STRING. Эта структура включает буфер, содержащий исходную строку. Эта строка будет добавлена в конец конечной строки. Максимальное количество байтов в строковом буфере структуры — NTSTRSAFE_UNICODE_STRING_MAX_CCH * sizeof(WCHAR).

[in] cbToAppend

Максимальное количество байтов, добавляемых к строке, описанной параметром DestinationString.

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

RtlUnicodeStringCbCatN возвращает одно из следующих значений NTSTATUS.

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

RtlUnicodeStringCbCatN возвращает значение STATUS_INVALID_PARAMETER при возникновении одной из следующих ситуаций:

Содержимое структуры UNICODE_STRING недопустимо.
Буфер назначения уже заполнен.
Указатель буфера NULL.
Длина целевого буфера равна нулю, но в исходной строке ненулевой длины присутствует.
Значение параметра cbToAppend больше NTSTRSAFE_UNICODE_STRING_MAX_CCH * sizeof(WCHAR).

Сведения об тестировании значений NTSTATUS см. в использование значений NTSTATUS.

Замечания

Функция RtlUnicodeStringCbCatN использует размер буфера назначения, чтобы убедиться, что операция объединения не записывает в конец буфера. Функция не завершает результирующая строка со значением NULL (то есть с нулем).

Если исходные и конечные строки перекрываются, поведение функции не определено.

Указатели SourceString и DestinationString не могут быть NULL. Если необходимо обработать значения указателя null NULL, используйте функцию RtlUnicodeStringCbCatNEx.

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

Требования

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

См. также

RtlUnicodeStringCbCatNEx

RtlUnicodeStringCchCatN

UNICODE_STRING

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