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

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

  • Статья

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

Синтаксис

NTSTRSAFEDDI RtlStringCbCopyUnicodeStringEx(
  [out]           NTSTRSAFE_PWSTR  pszDest,
  [in]            size_t           cbDest,
  [in]            PCUNICODE_STRING SourceString,
  [out]           NTSTRSAFE_PWSTR  *ppszDestEnd,
  [out, optional] size_t           *pcbRemaining,
  [in]            DWORD            dwFlags
);

Параметры

[out] pszDest

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

[in] cbDest

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

[in] SourceString

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

[out] ppszDestEnd

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

[out, optional] pcbRemaining

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

[in] dwFlags

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

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

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

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

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

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

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

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

Замечания

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

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

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

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

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

Требования

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

См. также