Функция StringCchPrintfA (strsafe.h)
Записывает форматированные данные в указанную строку. Размер буфера назначения предоставляется функции, чтобы гарантировать, что она не будет записывать данные после конца этого буфера.
StringCchPrintf является заменой следующих функций:
Синтаксис
STRSAFEAPI StringCchPrintfA(
[out] STRSAFE_LPSTR pszDest,
[in] size_t cchDest,
[in] STRSAFE_LPCSTR pszFormat,
...
);
Параметры
[out] pszDest
Тип: LPTSTR
Буфер назначения, который получает отформатированную строку со значением NULL, созданную из pszFormat , и его аргументы.
[in] cchDest
Тип: size_t
Размер буфера назначения в символах. Это значение должно быть достаточно большим, чтобы вместить окончательную отформатированную строку плюс 1 для учета завершающего символа NULL. Максимально допустимое количество символов — STRSAFE_MAX_CCH.
[in] pszFormat
Тип: LPCTSTR
Строка формата. Эта строка должна заканчиваться null. Дополнительные сведения см. в разделе Синтаксис спецификации формата.
...
Аргументы, которые необходимо вставить в строку pszFormat .
Возвращаемое значение
Тип: HRESULT
Эта функция может возвращать одно из следующих значений. Настоятельно рекомендуется использовать макросы SUCCEEDED и FAILED для проверки возвращаемого значения этой функции.
Код возврата | Описание |
---|---|
|
Было достаточно места для копирования результата в pszDest без усечения, и буфер завершается null. |
|
Значение в cchDest равно 0 или больше STRSAFE_MAX_CCH. |
|
Операция копирования завершилась сбоем из-за нехватки места в буфере. Буфер назначения содержит усеченную версию предполагаемого результата, завершаемую null. В ситуациях, когда усечение является приемлемым, это не обязательно может рассматриваться как условие сбоя. |
Обратите внимание, что эта функция возвращает значение HRESULT , в отличие от функций, которые она заменяет.
Комментарии
По сравнению с функциями, которые он заменяет, StringCchPrintf обеспечивает дополнительную обработку для правильной обработки буфера в коде. Плохая обработка буфера связана со многими проблемами безопасности, которые связаны с переполнением буфера. StringCchPrintf всегда завершает ненулевой буфер назначения.
Поведение не определено, если строки, на которые указывают pszDest, pszFormat или любые строки аргументов, перекрываются.
Ни pszFormat , ни pszDest не должны иметь значение NULL. Если требуется обработка значений указателя null, см. раздел StringCchPrintfEx .
StringCchPrintf можно использовать в его универсальной форме или в более конкретных формах. Тип данных строки определяет форму этой функции, которую следует использовать.
Тип данных String | Строковый литерал | Функция |
---|---|---|
char | Строка | StringCchPrintfA |
TCHAR | TEXT("string") | StringCchPrintf |
WCHAR | L"string" | StringCchPrintfW |
Примеры
В следующем примере показано простое использование StringCchPrintf с использованием четырех аргументов.
TCHAR pszDest[30];
size_t cchDest = 30;
LPCTSTR pszFormat = TEXT("%s %d + %d = %d.");
TCHAR* pszTxt = TEXT("The answer is");
HRESULT hr = StringCchPrintf(pszDest, cchDest, pszFormat, pszTxt, 1, 2, 3);
// The resultant string at pszDest is "The answer is 1 + 2 = 3."
Примечание
Заголовок strsafe.h определяет StringCchPrintf в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
Требование | Значение |
---|---|
Минимальная версия клиента | Windows XP с пакетом обновления 2 (SP2) [классические приложения | Приложения UWP] |
Минимальная версия сервера | Windows Server 2003 с пакетом обновления 1 (SP1) [классические приложения | Приложения UWP] |
Целевая платформа | Windows |
Header | strsafe.h |
См. также раздел
Справочные материалы