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

Функции RtlStringCchCopyNExW и RtlStringCchCopyNExA копируют число символьных строк в буфер, ограничивая размер скопированной строки.

Синтаксис

NTSTRSAFEDDI RtlStringCchCopyNExA(
  [out, optional] NTSTRSAFE_PSTR pszDest,
  [in]            size_t         cchDest,
  [in, optional]  STRSAFE_PCNZCH pszSrc,
                  size_t         cchToCopy,
  [out, optional] NTSTRSAFE_PSTR *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. Если pszDestNULL, cchDest должно быть равно нулю.

[in, optional] pszSrc

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

cchToCopy

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

[out, optional] ppszDestEnd

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

[out, optional] pcchRemaining

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

[in] dwFlags

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

Ценность	Значение
STRSAFE_FILL_BEHIND_NULL	Если этот флаг задан и функция успешно выполнена, то для заполнения части конечного буфера используется низкий байт dwFlags.
STRSAFE_IGNORE_NULLS	Если этот флаг задан, pszDest или pszSrcили оба параметра могут быть NULL. NULLуказатели pszSrc обрабатываются как пустые строки (TEXT("")), которые можно скопировать. nullpszDest указатели не могут получать строки nonempty.
STRSAFE_FILL_ON_FAILURE	Если этот флаг задан и функция завершается ошибкой, то для заполнения всего целевого буфера используется низкий байт dwFlags. Эта операция перезаписывает все предварительно существующие содержимое буфера.
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, дополнительные сведения см. в параметре dwFlags dwFlags.
STATUS_INVALID_PARAMETER	Это ошибка состоянии означает, что функция получила недопустимый входной параметр. Дополнительные сведения см. в следующем абзаце. Функция возвращает значение STATUS_INVALID_PARAMETER, если: Указан недопустимый флаг. Значение в cchDest больше максимального размера буфера. Буфер назначения уже заполнен. Указатель NULL присутствует без флага STRSAFE_IGNORE_NULLS. Указатель целевого буфера был NULL, но размер буфера не был нулем. Указатель на целевой буфер был null, или его длина составила нулю, но в исходной строке ненулевой длины присутствует.

Замечания

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

Обратите внимание, что эти функции ведут себя по-разному от strncpy в одном отношении. Если cchSrc больше количества символов в pszSrc, RtlStringCchCopyNExW и RtlStringCchCopyNExA , в отличие от strncpy, не продолжайте pszDest с пустыми символами, пока не будут скопированы cchSrc символов.

RtlStringCchCopyNExW и RtlStringCchCopyNExA добавить в функциональные возможности RtlStringCchCopyN, возвращая указатель на конец конечной строки, а также количество символов, оставшихся неиспользуемыми в этой строке. Флаги можно передать функции для дополнительного элемента управления.

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

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

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

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

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

Требования

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

См. также

• RtlStringCbCopyNEx
• RtlStringCchCopyN