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

Статья
07/16/2024

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

Синтаксис

NTSTRSAFEDDI RtlStringCchPrintfExA(
  [out, optional] NTSTRSAFE_PSTR  pszDest,
  [in]            size_t          cchDest,
  [out, optional] NTSTRSAFE_PSTR  *ppszDestEnd,
  [out, optional] size_t          *pcchRemaining,
  [in]            DWORD           dwFlags,
  [in]            NTSTRSAFE_PCSTR pszFormat,
                  ...             
);

Параметры

[out, optional] pszDest

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

[in] cchDest

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

[out, optional] ppszDestEnd

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

[out, optional] pcchRemaining

Если вызывающий объект предоставляет указатель адреса, отличного от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] pszFormat

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

Замечания

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

спринтфа
swprintf
_snprintf
_snwprintf

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

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

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

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

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

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

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

Требования

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

См. также

RtlStringCbPrintfEx

RtlStringCchPrintf

RtlStringCchVPrintfEx

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