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

Функции RtlStringCbCopyW и RtlStringCbCopyA копируют строку с подсчетом байтов в буфер.

Синтаксис

NTSTRSAFEDDI RtlStringCbCopyA(
  [out] NTSTRSAFE_PSTR  pszDest,
  [in]  size_t          cbDest,
  [in]  NTSTRSAFE_PCSTR pszSrc
);

Параметры

[out] pszDest

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

[in] cbDest

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

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

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

[in] pszSrc

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

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

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

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

Комментарии

Вместо следующих функций следует использовать RtlStringCbCopyA и RtlStringCbCopyW:

• strcpy
• wcscpy

RtlStringCbCopyA и RtlStringCbCopyW не заменяют strncpy. Чтобы заменить strncpy, используйте RtlStringCbCopyN или RtlStringCbCopyNEx.

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

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

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

 

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

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

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

Требования

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

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

RtlStringCbCopyEx

RtlStringCchCopy