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

Статья
07/16/2024

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

Синтаксис

NTSTRSAFEDDI RtlStringCbVPrintfExW(
  [out, optional] NTSTRSAFE_PWSTR  pszDest,
  [in]            size_t           cbDest,
  [out, optional] NTSTRSAFE_PWSTR  *ppszDestEnd,
  [out, optional] size_t           *pcbRemaining,
  [in]            DWORD            dwFlags,
  [in, optional]  NTSTRSAFE_PCWSTR pszFormat,
  [in]            va_list          argList
);

Параметры

[out, optional] pszDest

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

[in] cbDest

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

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

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

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

[out, optional] ppszDestEnd

Если вызывающий объект предоставляет указатель адреса, отличный от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 для заполнения всего целевого буфера, а буфер завершается значением 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, если: Указан недопустимый флаг. Значение в cbDest больше максимального размера буфера. Буфер назначения уже заполнен. Указатель NULL присутствует без флага STRSAFE_IGNORE_NULLS. Указатель целевого буфера был NULL, но размер буфера не был нулем. Указатель на целевой буфер был null, или его длина составила нулю, но в исходной строке ненулевой длины присутствует.

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

Описание

STATUS_SUCCESS

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

STATUS_BUFFER_OVERFLOW

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

STATUS_INVALID_PARAMETER

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

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

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

Замечания

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

vsprintf
vswprintf
_vsnprintf
_vsnwprintf

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

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

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

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

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

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

Ни pszFormat, ни pszDest не могут быть NULL, если флаг STRSAFE_IGNORE_NULLS не задан, в этом случае можно значение NULL. Если pszDestNULL, pszFormat должен быть NULL или указывать на пустую строку.

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

Требования

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

См. также

RtlStringCbPrintfEx

RtlStringCbVPrintf

RtlStringCchVPrintfEx

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