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

Статья
08/07/2023

Функция RtlUnicodeStringCchCopyN копирует строку из одной структуры UNICODE_STRING в другую, ограничивая размер скопированной строки.

Синтаксис

NTSTRSAFEDDI RtlUnicodeStringCchCopyN(
  [out] PUNICODE_STRING  DestinationString,
  [in]  PCUNICODE_STRING SourceString,
  [in]  size_t           cchToCopy
);

Параметры

[out] DestinationString

Указатель на структуру UNICODE_STRING , получающую скопированную строку. Строка, на которую указывает структура UNICODE_STRING параметра SourceString, копируется в буфер, на который указывает структура UNICODE_STRING параметра DestinationString. Максимальное количество символов в строковом буфере структуры равно NTSTRSAFE_UNICODE_STRING_MAX_CCH.

[in] SourceString

Указатель на структуру UNICODE_STRING , содержащую копируемые строки. Максимальное количество символов в строковом буфере структуры равно NTSTRSAFE_UNICODE_STRING_MAX_CCH.

[in] cchToCopy

Количество символов, копируемых из источника в место назначения.

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

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

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

RtlUnicodeStringCchCopyN возвращает значение STATUS_INVALID_PARAMETER при выполнении одного из следующих действий:

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

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

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

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

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

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

Требования

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

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

RtlUnicodeStringCchCopyN

RtlUnicodeStringCchCopyNEx

UNICODE_STRING