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

  • Статья

Функции 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 * sizeof(WCHAR).

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

[in] pszSrc

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

cbToCopy

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

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

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

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

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

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

Комментарии

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

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

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

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

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

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

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

Требования

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

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

RtlStringCbCopy

RtlStringCbCopyNEx

RtlStringCchCopyN