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