Поделиться через

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

  • Статья

Функция RtlStringCchCopyUnicodeStringEx копирует содержимое структуры UNICODE_STRING в указанное назначение.

Синтаксис

NTSTRSAFEDDI RtlStringCchCopyUnicodeStringEx(
  [out]           NTSTRSAFE_PWSTR  pszDest,
  [in]            size_t           cchDest,
  [in]            PCUNICODE_STRING SourceString,
  [out]           NTSTRSAFE_PWSTR  *ppszDestEnd,
  [out, optional] size_t           *pcchRemaining,
  [in]            DWORD            dwFlags
);

Параметры

[out] pszDest

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

[in] cchDest

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

[in] SourceString

Необязательный. Указатель на структуру UNICODE_STRING, содержащую скопированную строку. Максимальное число символов в строке равно NTSTRSAFE_UNICODE_STRING_MAX_CCH. Этот указатель может быть null, но только если STRSAFE_IGNORE_NULLS заданы в dwFlags.

[out] ppszDestEnd

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

[out, optional] pcchRemaining

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

[in] dwFlags

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

Ценность Значение
STRSAFE_FILL_BEHIND_NULL Если этот флаг задан и функция успешно выполнена, то для заполнения части конечного буфера используется низкий байт dwFlags.
STRSAFE_IGNORE_NULLS Если этот флаг задан, то исходный или конечный указатель можно null. RtlStringCchCopyUnicodeStringEx обрабатывает null указатели исходного буфера, такие как пустые строки (TEXT("")), которые можно копировать. указатели буфера назначения null не могут получать строки 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 игнорируется.

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

RtlStringCchCopyUnicodeStringEx возвращает одно из следующих значений NTSTATUS.

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

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

  • Содержимое структуры UNICODE_STRING недопустимо.
  • Недопустимый флаг указан в dwFlags.
  • Значение в cchDest больше максимального размера буфера.
  • Целевой буфер (который pszDest указывает на) уже заполнен.
  • Указатель буфера значение NULL, а флаг STRSAFE_IGNORE_NULLS не указан.
  • Указатель буфера назначения null, но размер буфера не равен нулю.
  • Указатель целевого буфера равен значение NULL или его длина равна нулю, но строка источника ненулевой длины присутствует.

Сведения об тестировании значений NTSTATUS см. в использование значений NTSTATUS.

Замечания

Функция RtlStringCchCopyUnicodeStringEx использует размер буфера назначения (который указывает параметр cchDest cchDest), чтобы убедиться, что операция копирования не записывается в конец буфера.

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

Если исходные и конечные строки перекрываются, поведение функции не определено.

Указатели *SourceString *и pszDest нельзя NULL, если флаг STRSAFE_IGNORE_NULLS не задан в dwFlags. Если STRSAFE_IGNORE_NULLS задано, один или оба этих пункта могут быть NULL. Если указатель pszDest NULL, указатель SourceString должен быть NULL или структура UNICODE_STRING должна описать пустую строку.

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

Требования

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

См. также