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

Статья
02/07/2025

Функции RtlStringCbPrintfExW и RtlStringCbPrintfExA создают строку текста с подсчетом байтов с форматированием, основанной на предоставленных сведениях о форматировании.

Синтаксис

NTSTRSAFEDDI RtlStringCbPrintfExW(
  [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,
                  ...              
);

Параметры

[out, optional] pszDest

Указатель на буфер, предоставленный вызывающим, который получает отформатированную строку, завершающуюся значением NULL. Функция создает эту строку из строки форматирования, предоставленной pszFormat и списка аргументов функции. Указатель 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, которая содержит -styled директив форматирования. Указатель pszFormat может быть null, но только если STRSAFE_IGNORE_NULLS задан в dwFlags.

...

Список аргументов, интерпретируемых функцией, на основе директив форматирования, содержащихся в строке 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, или его длина составила нулю, но в исходной строке ненулевой длины присутствует.

Замечания

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

спринтфа
swprintf
_snprintf
_snwprintf

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

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

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

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

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

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

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

Требования

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

См. также

RtlStringCbVPrintfEx

RtlStringCchPrintf

RtlStringCchPrintfEx

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