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

Статья
07/16/2024

Функции RtlStringCchVPrintfExW и RtlStringCchVPrintfExA создают строку с подсчетом символов с форматированием, основанной на предоставленной информации о форматировании.

Синтаксис

NTSTRSAFEDDI RtlStringCchVPrintfExW(
  [out]           NTSTRSAFE_PWSTR  pszDest,
  [in]            size_t           cchDest,
  [out, optional] NTSTRSAFE_PWSTR  *ppszDestEnd,
  [out, optional] size_t           *pcchRemaining,
  [in]            DWORD            dwFlags,
  [in, optional]  NTSTRSAFE_PCWSTR pszFormat,
  [in]            va_list          argList
);

Параметры

[out] pszDest

Указатель на буфер, предоставленный вызывающим, который получает отформатированную строку, завершающуюся значением NULL. Функция создает эту строку как из строки форматирования, предоставленной pszFormat, так и аргументов, предоставляемых argList. Указатель pszDest можно null, но только если STRSAFE_IGNORE_NULLS задан в dwFlags.

[in] cchDest

Размер целевого буфера в символах. Буфер должен быть достаточно большим, чтобы содержать отформатированную строку, а также завершающий символ NULL. Максимально допустимое количество символов — NTSTRSAFE_MAX_CCH. Если pszDestNULL, cchDest должно быть равно нулю.

[out, optional] ppszDestEnd

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

[out, optional] pcchRemaining

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

[in] dwFlags

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

Ценность	Значение
STRSAFE_FILL_BEHIND_NULL	Если задано и функция успешно выполнена, то для заполнения части конечного буфера используется низкий байт dwFlags.
STRSAFE_IGNORE_NULLS	Если задано, pszDest можно NULL. nullpszDest указатели не могут получать строки nonempty.
STRSAFE_FILL_ON_FAILURE	Если задано и функция завершается ошибкой, используется низкий байт dwFlags для заполнения всего целевого буфера, а буфер завершается значением NULL. Эта операция перезаписывает все предварительно существующие содержимое буфера.
STRSAFE_NULL_ON_FAILURE	Если задано и функция завершается ошибкой, буфер назначения имеет пустую строку (TEXT("")). Эта операция перезаписывает все предварительно существующие содержимое буфера.
STRSAFE_NO_TRUNCATION	Если задано и функция возвращает STATUS_BUFFER_OVERFLOW, содержимое целевого буфера не изменяется.

[in, optional] pszFormat

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

[in] argList

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

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

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

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

Возвращаемый код

Описание

STATUS_SUCCESS

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

STATUS_BUFFER_OVERFLOW

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

STATUS_INVALID_PARAMETER

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

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

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

Замечания

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

vsprintf
vswprintf
_vsnprintf
_vsnwprintf

Все эти функции принимают строку формата и его аргументы, предоставляемые в виде списка аргументов va_listтипа и возвращают отформатированную строку. RtlStringCchVPrintfExW и RtlStringCchVPrintfExA получать размер в символах целевого буфера, чтобы они не записывали после конца буфера.

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

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

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

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

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

pszDest нельзя значение NULL, если флаг STRSAFE_IGNORE_NULLS не задан.

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

Требования

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

См. также

RtlStringCbVPrintfEx

RtlStringCchPrintfEx

RtlStringCchVPrintf

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