Функция StringCbPrintfW (strsafe.h)

Статья
08/26/2023

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

StringCbPrintf является заменой следующих функций:

Синтаксис

STRSAFEAPI StringCbPrintfW(
  [out] STRSAFE_LPWSTR  pszDest,
  [in]  size_t          cbDest,
  [in]  STRSAFE_LPCWSTR pszFormat,
        ...             
);

Параметры

[out] pszDest

Тип: LPTSTR

Буфер назначения, который получает отформатированную строку со значением NULL, созданную из pszFormat , и его аргументы.

[in] cbDest

Тип: size_t

Размер буфера назначения в байтах. Это значение должно быть достаточно большим, чтобы вместить окончательную отформатированную строку и завершающий символ NULL. Максимально допустимое число байтов — STRSAFE_MAX_CCH * sizeof(TCHAR).

[in] pszFormat

Тип: LPCTSTR

Строка формата. Эта строка должна заканчиваться null. Дополнительные сведения см. в разделе Синтаксис спецификации формата.

...

Аргументы, которые необходимо вставить в строку pszFormat .

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

Тип: HRESULT

Эта функция может возвращать одно из следующих значений. Настоятельно рекомендуется использовать макросы SUCCEEDED и FAILED для проверки возвращаемого значения этой функции.

Код возврата	Описание
S_OK	Было достаточно места для копирования результата в pszDest без усечения, и буфер завершается null.
STRSAFE_E_INVALID_PARAMETER	Значение в cbDest равно 0 или больше `STRSAFE_MAX_CCH * sizeof(TCHAR)`.
STRSAFE_E_INSUFFICIENT_BUFFER	Операция копирования завершилась сбоем из-за нехватки места в буфере. Буфер назначения содержит усеченную версию предполагаемого результата, завершаемую null. В ситуациях, когда усечение является приемлемым, это не обязательно может рассматриваться как условие сбоя.

Обратите внимание, что эта функция возвращает значение HRESULT , в отличие от функций, которые она заменяет.

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

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

Ни pszFormat , ни pszDest не должны иметь значение NULL. Если требуется обработка значений указателя null, см. раздел StringCbPrintfEx .

StringCbPrintf можно использовать в его универсальной форме или в более конкретных формах. Тип данных строки определяет форму этой функции, которую следует использовать.

Тип данных String	Строковый литерал	Функция
char	Строка	StringCbPrintfA
TCHAR	TEXT("string")	StringCbPrintf
WCHAR	L"string"	StringCbPrintfW

Примеры

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

int const arraysize = 30;
TCHAR pszDest[arraysize]; 
size_t cbDest = arraysize * sizeof(TCHAR);

LPCTSTR pszFormat = TEXT("%s %d + %d = %d.");
TCHAR* pszTxt = TEXT("The answer is");

HRESULT hr = StringCbPrintf(pszDest, cbDest, pszFormat, pszTxt, 1, 2, 3);

// The resultant string at pszDest is "The answer is 1 + 2 = 3."

Примечание

Заголовок strsafe.h определяет StringCbPrintf в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования


Минимальная версия клиента	Windows XP с пакетом обновления 2 (SP2) [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 с пакетом обновления 1 (SP1) [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	strsafe.h

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

Справочные материалы

StringCbPrintfEx

StringCbVPrintf

StringCchPrintf

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