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

Статья
02/29/2024

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

Синтаксис

NTSTRSAFEDDI RtlUnicodeStringCbCopyN(
  [out] PUNICODE_STRING  DestinationString,
  [in]  PCUNICODE_STRING SourceString,
  [in]  size_t           cbToCopy
);

Параметры

[out] DestinationString

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

[in] SourceString

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

[in] cbToCopy

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

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

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

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

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

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

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

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

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

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

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

Требования

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

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

RtlUnicodeStringCbCopyNEx

RtlUnicodeStringCchCopyN

UNICODE_STRING