Функция StringCbPrintf

Функция StringCbPrintf - это замена функции sprintf. Она принимает формат строки и список аргументов, объединяет их и возвращает форматированную строку. Размер, в байтах, целевого буфера назначается для функции таким, чтобы гарантировать, что StringCbPrintf не запишет помимо конца этого буфера.

Синтаксис

HRESULT StringCbPrintf(      

    LPTSTR pszDest,
    size_t cbDest,
    LPCTSTR pszFormat,
     ...
);

Параметры

pszDest

[out] Указатель на буфер, который принимает форматированную, с завершающим нулем строку, созданную в соответствии с параметром pszFormat и его аргументов.

cbDest

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

pszFormat

[in] Указатель на буфер, содержащий в себе форматирующая строку printf-стиля. Эта строка должна быть завершена символом конца строки ('\0').

...

[in] Параметры, которые будут вставлены в параметр pszFormat.

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

Обратите внимание! на то, что функция возвращает значение HRESULT в противоположность функции sprintf, которая возвращает число байтов, сохраненных в её целевом буфере. Поэтому настоятельно рекомендуется, чтобы вы использовали макросы SUCCEEDED и FAILED для проверки возвращаемого значения этой функцией.

 

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

Описание

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

Замечания

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

Функция StringCbPrintf может быть использована в её унифицированной форме, или в специальной, как StringCbPrintfA (для строк ANSI) или StringCbPrintfW (для Unicode-строк). Форма, которая используется, определяется Вашими данными.

Тип данных строки

Литерал строки

Функция

char "string" StringCbPrintfA
TCHAR TEXT("string") StringCbPrintf
WCHAR L"string" StringCbPrintfW

Функция StringCbPrintf и её ANSI и Unicode варианты - заменяют эти функции:

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

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

Пример

Пример ниже показывает основное использование функции 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);

// Результирующая строка в параметре pszDest - "Ответ - 1 +  2 = 3."

 

Смотри также

Обзор Строки, Функции, используемые строкамиStringCchPrintf, StringCbPrintfEx, StringCbVPrintf

Размещение и совместимость StringCbPrintf

К Windows XP Да
л Windows 2000 Professional Да
и Windows NT Workstation Да версии 3.1
е Windows Me Да
н Windows 98 Да
т Windows 95 Да
 
С Windows Server 2003 Да
е Windows 2000 Server Да
р Windows NT Server Да версии 3.1
в    
е    
р    
Используемая библиотека strsafe.lib
Используемая DLL -
Заголовочный файл  
- объявлено в strsafe.h
- включено в -
Unicode Реализуются как версии Unicode и ANSI.
Замечания по платформе Не имеется

 

Назад в оглавление
На главную страницу
В оглавление справки

Hosted by uCoz