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

  • Статья

Функции RtlStringCchCopyW и RtlStringCchCopyA копируют исходную строку с завершением NULL в целевой буфер указанной длины.

Синтаксис

NTSTRSAFEDDI RtlStringCchCopyW(
  [out] NTSTRSAFE_PWSTR  pszDest,
  [in]  size_t           cchDest,
  [in]  NTSTRSAFE_PCWSTR pszSrc
);

Параметры

[out] pszDest

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

[in] cchDest

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

[in] pszSrc

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

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

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

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

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

  • Значение в cchDest больше максимального размера буфера.
  • Существовал указатель NULL .
  • Длина целевого буфера на входе равна нулю.

Комментарии

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

  • strcpy
  • wcscpy
Эти функции не заменяют strncpy. Используйте RtlStringCchCopyN или RtlStringCchCopyNEx для замены strncpy.

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

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

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

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

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

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

Требования

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

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

RtlStringCbCopy

RtlStringCchCopyEx