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


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

Функции RtlStringCchPrintfW и RtlStringCchPrintfA создают текстовую строку со счетчиком символов с форматированием на основе предоставленных сведений о форматировании.

Синтаксис

NTSTRSAFEDDI RtlStringCchPrintfW(
  [out] NTSTRSAFE_PWSTR  pszDest,
  [in]  size_t           cchDest,
  [in]  NTSTRSAFE_PCWSTR pszFormat,
        ...              
);

Параметры

[out] pszDest

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

[in] cchDest

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

[in] pszFormat

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

...

Список аргументов, интерпретируемых функцией, на основе директив форматирования, содержащихся в строке pszFormat .

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

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

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

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

  • Значение в cchDest больше максимального размера буфера.
  • Целевой буфер уже заполнен.
  • Существовал указатель NULL .
  • Длина целевого буфера равна нулю, но при этом присутствовала строка источника ненулевой длины.

Комментарии

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

  • sprintf
  • swprintf
  • _snprintf
  • _snwprintf
Все эти функции принимают строку формата и список аргументов и возвращают форматированную строку. RtlStringCchPrintfW и RtlStringCchPrintfA принимают размер (в символах) целевого буфера, чтобы гарантировать, что функции не записывают данные за конец буфера.

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

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

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

Ни pszFormat, ни pszDest не могут иметь значение NULL. Если необходимо обрабатывать значения строкового указателя NULL, используйте RtlStringCchPrintfEx.

Примеры

В следующем примере показано простое использование RtlStringCchPrintfW с использованием четырех аргументов.

WCHAR pszDest[30]; 
size_t cchDest = 30;

LPCWSTR pszFormat = L"%s %d + %d = %d.";
WCHAR* pszTxt = L"The answer is";

NTSTATUS status = 
    RtlStringCchPrintfW(pszDest, cchDest, pszFormat, pszTxt, 1, 2, 3);

Результирующей строкой является "Ответ равен 1 + 2 = 3". Он содержится в буфере по адресу pszDest.

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

Требования

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

См. также раздел

RtlStringCbPrintf

RtlStringCchPrintfEx

RtlStringCchVPrintf