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