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

Статья
02/07/2025

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

Синтаксис

NTSTRSAFEDDI RtlStringCbCopyNA(
  [out] NTSTRSAFE_PSTR pszDest,
  [in]  size_t         cbDest,
  [in]  STRSAFE_PCNZCH pszSrc,
        size_t         cbToCopy
);

Параметры

[out] pszDest

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

[in] cbDest

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

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

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

[in] pszSrc

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

cbToCopy

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

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

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

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

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

Описание

STATUS_SUCCESS

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

STATUS_BUFFER_OVERFLOW

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

STATUS_INVALID_PARAMETER

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

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

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

Замечания

RtlStringCbCopyNW и RtlStringCbCopyNA следует использовать вместо strncpy. Однако эти функции отличаются в поведении. Если cbSrc больше, чем количество байтов в pszSrc, функции RtlStringCbCopyN , в отличие от strncpy, не заполняйте pszDest с пустыми символами, пока cbSrc байты не будут скопированы.

RtlStringCbCopyN копирует заданное число байтов из исходной строки. Размер в байтах целевого буфера предоставляется функции, чтобы гарантировать, что RtlStringCbCopyN не записывает в конец этого буфера.

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

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

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

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

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

Требования

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

См. также

RtlStringCbCopy

RtlStringCbCopyNEx

RtlStringCchCopyN

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