Функция StringCbVPrintfEx - это замена для функции vsprintf. Она принимает форматируемую строку и ее параметры, предусмотренные как va_list, и возвращает форматированную строку. Размер, в байтах, целевого буфера назначается в функцию для того, чтобы гарантировать, что StringCbVPrintfEx не запишет помимо конца этого буфера. StringCbVPrintfEx добавляет к функциональным возможностям функции StringCbVPrintf возврат указателя на конец строки, являющейся выходным значением, а так же, число байтов, оставшееся неиспользованным в этой строке. В функцию для дополнительного управления могут также передаваться флажки.
HRESULT StringCbVPrintfEx( LPTSTR pszDest, size_t cbDest, LPTSTR *ppszDestEnd, size_t *pcbRemaining, DWORD dwFlags, LPCTSTR pszFormat, va_list argList ); |
[out] Указатель на буфер, который получает форматированную строку с завершающим нулем, созданную из параметров pszFormat и argList.
cbDest[in] Размер целевого буфера, в байтах. Это значение должно быть достаточно большим, чтобы вместить конечную форматированную строку, плюс символ завершающего нуля. Максимально допустимое число байтов - STRSAFE_MAX_CCH * sizeof (TCHAR).
ppszDestEndАдрес указателя на конец строки в pszDest. Если ppszDestEnd не-NULL, и какие-либо данные копируются в целевой буфер, он указывает на символ завершающего нуля в конце строки.
pcbRemaining[out] Указатель на переменную, которая обозначает число неиспользуемых байтов в pszDest, включая и те, которые используется для символа завершающего нуля. Если pcbRemaining - NULL, подсчет не сохраняется или возвращается значение.
dwFlags[in] Это одно или несколько из нижеследующих значений.
Флажок |
Предназначение |
| STRSAFE_FILL_BEHIND_NULL | Если функция завершается успешно, младший байт dwFlags (0) используется, чтобы заполнить неинициализированную часть pszDest после символа завершающего нуля. |
| STRSAFE_IGNORE_NULLS | Обрабатывает указатели пустой строки подобно пустым строкам (TEXT ("")). |
| STRSAFE_FILL_ON_FAILURE | Если функция завершается ошибкой, младший байт dwFlags (0) используется, чтобы заполнить весь буфер pszDest, а буфер завершается символом конца строки ('\0'). В случае сбоя типа STRSAFE_E_INSUFFICIENT_BUFFER любая обрезанная строка возвращается переписанной. |
| STRSAFE_NULL_ON_FAILURE | Если функция завершается ошибкой, pszDest устанавливается в пустую строку ( TEXT ("")). В случае сбоя типа STRSAFE_E_INSUFFICIENT_BUFFER, любая обрезанная строка переписывается. |
| STRSAFE_NO_TRUNCATION | Как и в случае STRSAFE_NULL_ON_FAILURE, если функция завершается ошибкой, pszDest устанавливается в пустую строку ( TEXT ("")). В случае сбоя типа STRSAFE_E_INSUFFICIENT_BUFFER любая обрезанная строка - переписывается. |
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 | Операция копирования завершилась ошибкой из-за недостаточного пространства буфера. В зависимости от значения dwFlags, целевой буфер может содержать в себе обрезанную версию с нулевым символом в конце версии предполагаемого результата. В ситуациях, где усечение является приемлемым, это может не обязательно быть отмечено как условие сбоя. |
Функция StringCbVPrintfEx предусматривает дополнительную обработку для правильного действия буфера в Вашем коде. Недостаточная обработка буфера влечется за собой многие проблемы обеспечения безопасности, которые вызывают переполнение буфера. StringCbVPrintfEx всегда завершает символом конца строки ('\0') целевой буфер ненулевой длины.
Дополнительную информацию об va_lists, см. в соглашениях, определенных в заголовочном файле Stdarg.h.
Функция StringCbVPrintfEx может быть использована в своей общей форме, или в специальной, такой как StringCbVPrintfExA (для строк ANSI) или StringCbVPrintfExW (для строк Unicode). Форма её использования определяется Вашими данными.
Тип данных строки |
Литерал строки |
Функция |
|---|---|---|
| char | "string" | StringCbVPrintfExA |
| TCHAR | TEXT("string") | StringCbVPrintfEx |
| WCHAR | L"string" | StringbCbVPrintfExW |
Функция StringCbVPrintfEx и её ANSI и Unicode варианты - заменяют эти функции:
Поведение неопределенное, если строки указанные при помощи pszDest, pszFormat, или какие-либо параметры строк перекрываются.
Ни pszFormat, ни pszDest не должны быть NULL, если не определяется флажок STRSAFE_IGNORE_NULLS, тогда в этом случае, оба могут быть NULL. Однако, ошибка из-за недостаточного пространства может все еще возвратиться даже при том, что игнорируются нулевые значения.
Обзор Строки, Функции, используемые строками, StringCchVPrintfEx, StringCbVPrintf, StringCbPrintfEx
Размещение и совместимость StringCbVPrintfEx |
||
| К | 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. | |
| Замечания по платформе | Не имеется | |
