Функция StringCbVPrintf - это замена для функции vsprintf. Она принимает форматирующую строку и ее параметры, предусмотренные как va_list и возвращает отформатированную строку. Размер, в байтах, целевого буфера назначается в функцию для того, чтобы гарантировать, что StringCbVPrintf не запишет помимо конца этого буфера.
HRESULT StringCbVPrintf( LPTSTR pszDest, size_t cbDest, LPCTSTR pszFormat, va_list argList ); |
[out] Указатель на буфер, который получает форматированную строку с завершающим нулем, созданную из параметров pszFormat и argList.
cbDest[in] Размер целевого буфера, в байтах. Это значение должно быть достаточно большим, чтобы вместить конечную форматированную строку, плюс символ завершающего нуля. Максимально допустимое число байтов - STRSAFE_MAX_CCH * sizeof (TCHAR).
pszFormat[in] Указатель на буфер, содержащий форматирующую строку printf-стиля. Эта строка должна быть завершена символом конца строки ('\0').
argList[in] Указатель на очередной аргумент va_list, содержащий в себе параметры, которые будут вставлены в pszFormat.
 Обратите внимание! на то, что функцией возвращается значение HRESULT в противоположность
функции vsprintf, которая возвращает число
прочитанных символов. Поэтому настоятельно рекомендуется, чтобы вы использовали макросы SUCCEEDED и
FAILED для проверки возвращаемого значения этой функцией. |
Значение |
Предназначение |
| S_OK | Было достаточно места для результата копирования в pszDest без усечения, а буфер завершен символом конца строки ('\0'). |
| STRSAFE_E_INVALID_PARAMETER | Значение в cbDest или 0, или больше, а не STRSAFE_MAX_CCH * sizeof (TCHAR). |
| STRSAFE_E_INSUFFICIENT_BUFFER | Операция копирования завершилась ошибкой из-за недостаточного пространства буфера. Целевой буфер содержит в себе обрезанную версию с нулевым символом в конце предполагаемого результата. В ситуациях, где усечение является приемлемым, это может не обязательно быть отмечено как условие сбоя. |
Функция StringCbVPrintf предусматривает дополнительные действия для правильной обработки буфера в Вашем коде. Плохая обработка буфера влечет за собой многие проблемы обеспечения безопасности, которые вызывают переполнение буфера. StringCbVPrintf всегда завершает символом конца строки ('\0') целевой буфер ненулевой длины.
Дополнительную информацию о va_lists, смотри в соглашении, определенном в заголовочном файле Stdarg.h.
StringCbVPrintf может быть использована в своей общей форме, или в специальной, такой как StringCbVPrintfA (для строк ANSI) или StringCbVPrintfW (для строк Unicode). Форма, которая используется, определяется Вашими данными.
Тип данных строки |
Литерал строки |
Функция |
|---|---|---|
| char | "string" | StringCbVPrintfA |
| TCHAR | TEXT("string") | StringCbVPrintf |
| WCHAR | L"string" | StringCbVPrintfW |
StringCbVPrintf и её ANSI и Unicode варианты - заменяют эти функции:
Поведение функции неопределенное, если строки указанные при помощи pszDest, pszFormat, или какие-либо параметры строк перекрываются.
Ни pszFormat, ни pszDest не должны быть NULL. См. описание StringCbVPrintfEx, если Вам требуется обработка значений указателя пустой строки.
Обзор Строки, Функции, используемые строками, StringCchVPrintf, StringCbVPrintfEx, StringCbPrintf
Размещение и совместимость StringCbVPrintf |
||
| К | 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. | |
| Замечания по платформе | Не имеется | |
