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

Статья
05/03/2024

Функция RtlUnicodeStringVPrintfEx создает текстовую строку с форматированием, основанным на предоставленных сведениях о форматировании, и сохраняет строку в UNICODE_STRING структуре.

Синтаксис

NTSTRSAFEDDI RtlUnicodeStringVPrintfEx(
  [out]           PUNICODE_STRING  DestinationString,
  [out, optional] PUNICODE_STRING  RemainingString,
  [in]            DWORD            dwFlags,
  [in]            NTSTRSAFE_PCWSTR pszFormat,
  [in]            va_list          argList
);

Параметры

[out] DestinationString

Необязательный параметр. Указатель на структуру UNICODE_STRING , получающую форматированную строку. RtlUnicodeStringVPrintfEx создает эту строку из строки форматирования, которую предоставляет pszFormat , и списка аргументов функции. Максимальное количество символов в строке — NTSTRSAFE_UNICODE_STRING_MAX_CCH. DestinationString может иметь значение NULL, но только если STRSAFE_IGNORE_NULLS задано в dwFlags.

[out, optional] RemainingString

Необязательный элемент. Если вызывающий объект предоставляет на структуру UNICODE_STRING указатель, отличный от NULL, то RtlUnicodeStringVPrintfE задает элемент Buffer этой структуры в конце форматируемой строки, задает элемент Length структуры равным нулю, а для элемента MaximumLength структуры — количество байтов, оставшихся в буфере назначения. Параметр RemainingString может иметь значение NULL, но только если STRSAFE_IGNORE_NULLS задано в dwFlags.

[in] dwFlags

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

STRSAFE_FILL_BEHIND

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

STRSAFE_IGNORE_NULLS

Если этот флаг установлен, указатель источника или назначения или и то, и другое может иметь значение NULL. RtlUnicodeStringVPrintfEx обрабатывает указатели исходного буфера NULL как пустые строки (TEXT("")), которые можно скопировать. Указатели буфера назначения NULL не могут получать непустые строки.

STRSAFE_FILL_ON_FAILURE

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

STRSAFE_NULL_ON_FAILURE

Если этот флаг установлен и функция завершается сбоем, для буфера назначения устанавливается пустая строка (TEXT("")). Эта операция перезаписывает все уже существующее содержимое буфера.

STRSAFE_NO_TRUNCATION

Если этот флаг установлен и функция возвращает STATUS_BUFFER_OVERFLOW, содержимое буфера назначения не изменяется.

STRSAFE_ZERO_LENGTH_ON_FAILURE

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

[in] pszFormat

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

[in] argList

Список аргументов с va_list типом. Аргументы в этом списке аргументов будут интерпретированы строкой форматирования using, которую предоставляет pszFormat .

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

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

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

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

Содержимое структуры UNICODE_STRING недопустимо.
В dwFlags указан недопустимый флаг.
Буфер назначения уже заполнен.
Указатель буфера имеет значение NULL , а флаг STRSAFE_IGNORE_NULLS не указан в dwFlags.
Указатель буфера назначения имеет значение NULL, но размер буфера не равен нулю.
Указатель буфера назначения имеет значение NULL или его длина равна нулю, но присутствует строка источника ненулевой длины.

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

Функция RtlUnicodeStringVPrintfEx использует размер буфера назначения, чтобы гарантировать, что операция форматирования строки не записывает данные за конец буфера. По умолчанию функция не завершает результирующую строку значением null (т. е. нулевым). В качестве варианта вызывающий объект может использовать флаг STRSAFE_FILL_BEHIND и значение байта байта заполнения, равное нулю, чтобы завершить результирующую строку, которая не занимает весь буфер назначения.

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

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

Указатели pszFormat и DestinationString не могут иметь значение NULL , если флаг STRSAFE_IGNORE_NULLS не установлен в dwFlags. Если задано STRSAFE_IGNORE_NULLS, один или оба из этих указателей могут иметь значение NULL. Если указатель DestinationString имеет значение NULL, то указатель pszFormat должен иметь значение NULL или указывать на пустую строку.

Дополнительные сведения о списках аргументов с типом va_list см. в документации по Microsoft Windows SDK.

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

Требования

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