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

Статья
11/20/2024

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

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

Синтаксис

STRSAFEAPI StringCbPrintfA(
  [out] STRSAFE_LPSTR  pszDest,
  [in]  size_t         cbDest,
  [in]  STRSAFE_LPCSTR pszFormat,
        ...            
);

Параметры

[out] pszDest

Тип: LPSTR

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

[in] cbDest

Тип: size_t

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

[in] pszFormat

Тип: LPCSTR

Строка формата. Эта строка должна быть завершена значением 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 можно использовать в универсальной форме или в более конкретных формах. Тип данных строки определяет форму этой функции, которую следует использовать.

Тип данных строки	Строковый литерал	Функция
char	"string"	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]
целевая платформа	Виндоус
заголовка	strsafe.h

См. также

Справочник

StringCbPrintfEx

StringCbVPrintf

StringCchPrintf

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