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

  • Статья

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

Синтаксис

NTSTRSAFEDDI RtlStringCbCopyExW(
  [out, optional] NTSTRSAFE_PWSTR  pszDest,
  [in]            size_t           cbDest,
  [in, optional]  NTSTRSAFE_PCWSTR pszSrc,
  [out, optional] NTSTRSAFE_PWSTR  *ppszDestEnd,
  [out, optional] size_t           *pcbRemaining,
  [in]            DWORD            dwFlags
);

Параметры

[out, optional] pszDest

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

[in] cbDest

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

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

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

Если pszDestNULL, cbDest должно быть равно нулю.

[in, optional] pszSrc

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

[out, optional] ppszDestEnd

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

[out, optional] pcbRemaining

Если вызывающий объект предоставляет указатель адресов, отличный от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.
STATUS_INVALID_PARAMETER

Это ошибка состоянии означает, что функция получила недопустимый входной параметр. Дополнительные сведения см. в следующем абзаце.

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

  • Указан недопустимый флаг.
  • Значение в cbDest больше максимального размера буфера.
  • Буфер назначения уже заполнен.
  • Указатель NULL присутствует без флага STRSAFE_IGNORE_NULLS.
  • Указатель целевого буфера был NULL, но размер буфера не был нулем.
  • Указатель на целевой буфер был null, или его длина составила нулю, но в исходной строке ненулевой длины присутствует.

Замечания

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

  • strcpy
  • wcscpy

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

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

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

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

Если 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

См. также