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

Статья
08/07/2023

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

Синтаксис

NTSTRSAFEDDI RtlStringCchCopyNA(
  [out] NTSTRSAFE_PSTR pszDest,
  [in]  size_t         cchDest,
  [in]  STRSAFE_PCNZCH pszSrc,
        size_t         cchToCopy
);

Параметры

[out] pszDest

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

[in] cchDest

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

[in] pszSrc

Указатель на строку, предоставляемую вызывающим, завершаемую null.

cchToCopy

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

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

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

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

Код возврата

Описание

STATUS_SUCCESS

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

STATUS_BUFFER_OVERFLOW

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

STATUS_INVALID_PARAMETER

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

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

Значение в cchDest больше максимального размера буфера.
Целевой буфер уже заполнен.
Существовал указатель NULL .
Длина целевого буфера равна нулю, но при этом присутствовала строка источника ненулевой длины.

Функции копируют заданное количество символов из исходной строки. RtlStringCchCopyNW и RtlStringCchCopyNA получают размер буфера назначения (в символах), чтобы гарантировать, что функции не записываются после конца буфера.

Обратите внимание, что эти функции ведут себя иначе, чем strncpy в одном отношении. Если cchSrc больше числа символов в pszSrc, RtlStringCchCopyNW и RtlStringCchCopyNA, в отличие от strncpy, не продолжайте добавлять в pszDest символы NULL, пока не будут скопированы символы cchSrc .

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

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

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

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

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

Требования

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

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

RtlStringCbCopyN

RtlStringCchCopy

RtlStringCchCopyNEx