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

Функции RtlStringCchCopyExW и RtlStringCchCopyExA копируют строку с подсчетом символов в буфер.

Синтаксис

NTSTRSAFEDDI RtlStringCchCopyExW(
  [out, optional] NTSTRSAFE_PWSTR  pszDest,
  [in]            size_t           cchDest,
  [in, optional]  NTSTRSAFE_PCWSTR pszSrc,
  [out, optional] NTSTRSAFE_PWSTR  *ppszDestEnd,
  [out, optional] size_t           *pcchRemaining,
  [in]            DWORD            dwFlags
);

Параметры

[out, optional] pszDest

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

[in] cchDest

Размер буфера назначения в символах. Максимально допустимое количество символов — NTSTRSAFE_MAX_CCH. Если pszDest имеет значение NULL, cchDest должен быть равен нулю.

[in, optional] pszSrc

Указатель на предоставленную вызывающей, завершаемую null строкой. Указатель pszSrc может иметь значение NULL, но только если STRSAFE_IGNORE_NULLS задано в dwFlags.

[out, optional] ppszDestEnd

Если вызывающий объект предоставляет указатель адреса, отличный от NULL , то после завершения операции копирования функция загружает этот адрес с указателем на результирующий символ конца строки null буфера назначения.

[out, optional] pcchRemaining

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

[in] dwFlags

Один или несколько флагов и, при необходимости, байт заполнения. Флаги определяются следующим образом:

Значение	Значение
STRSAFE_FILL_BEHIND_NULL	Если этот флаг установлен и функция выполняется успешно, для заполнения части буфера назначения, следующей за завершающим символом NULL, используется низкий байт dwFlags .
STRSAFE_IGNORE_NULLS	Если этот флаг установлен, pszDest , pszSrc или оба значения могут иметь значение NULL. Пустые указатели pszSrc обрабатываются как пустые строки (TEXT("")), которые можно скопировать. Указатели NULLpszDest не могут получать непустые строки.
STRSAFE_FILL_ON_FAILURE	Если этот флаг установлен и функция завершается сбоем, для заполнения всего целевого буфера используется низкий байт dwFlags , а буфер завершается значением NULL. Эта операция перезаписывает все уже существующее содержимое буфера.
STRSAFE_NULL_ON_FAILURE	Если этот флаг установлен и функция завершается сбоем, для буфера назначения устанавливается пустая строка (TEXT("")). Эта операция перезаписывает все уже существующее содержимое буфера.
STRSAFE_NO_TRUNCATION	Если этот флаг установлен и функция возвращает STATUS_BUFFER_OVERFLOW: Если также указан STRSAFE_FILL_ON_FAILURE , STRSAFE_NO_TRUNCATION соответствующим образом заполняет буфер назначения. В противном случае содержимому буфера назначения будет присвоена пустая строка, даже если STRSAFE_NULL_ON_FAILURE не задано. STRSAFE_FILL_BEHIND_NULL игнорируется.

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

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

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

Комментарии

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

• strcpy
• wcscpy

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

RtlStringCchCopyExW и RtlStringCchCopyExA добавляют к функциональным возможностям RtlStringCchCopy , возвращая указатель на конец строки назначения, а также количество символов, оставшихся в этой строке. Флаги можно передать в функцию для дополнительного управления. Используйте RtlStringCchCopyExW для обработки строк Юникода и RtlStringCchCopyExA для обработки строк ANSI. Используемая форма зависит от данных, как показано в следующей таблице.

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

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

Ни pszSrc, ни pszDest не могут иметь значение NULL , если не установлен флаг STRSAFE_IGNORE_NULLS. В этом случае оба значения могут иметь значение NULL. Если pszDest имеет значение NULL, pszSrc должен иметь значение NULL или указывать на пустую строку.

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

Требования

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

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

• RtlStringCbCopyEx
• RtlStringCchCopy