Функция StringCbPrintfEx - это замена функции sprintf. Она принимает форматирующую строку и список параметров и возвращает отформатированную строку. Размер, в байтах, буфера адресата предоставляется функции, чтобы гарантировать, что StringCbPrintfEx не запишет помимо конца этого буфера. Функция StringCbPrintfEx добавляет к функциональным возможностям StringCbPrintf, возврат указателя на конец строки назначения, а также число байтов, которое осталось неиспользованными в этой строке. В функцию для дополнительного управления можно также передать флажки.
HRESULT StringCbPrintfEx( LPTSTR pszDest, size_t cbDest, LPTSTR *ppszDestEnd, size_t *pcbRemaining, DWORD dwFlags, LPCTSTR pszFormat, ... ); |
[out] Указатель на буфер, который получает отформатированную, строку с нулевым символом в конце, созданную из pszFormat и его параметров.
cbDest[in] Размер целевого буфера, в байтах. Это значение должно быть достаточно большим, чтобы вместить конечную отформатированную строку, плюс символ завершающего нуля. Максимально допустимое число байтов - STRSAFE_MAX_CCH * sizeof (TCHAR).
ppszDestEnd[out] Адрес указателя на конец 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').
...
[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 | Операция копирования завершилась ошибкой из-за недостаточного размера буфера. В зависимости от значения dwFlags целевой буфер может содержать обрезанную версию строки с нулевым символом в конце предполагаемого результата. В ситуациях, где усечение допустимо, это может не обязательно быть отмечено как условие сбоя (завершения ошибкой). |
StringCbPrintfEx предусматривает дополнительную обработку для правильной работы буфера в Вашем коде. Плохая работа буфера влечет за собой многие проблемы обеспечения безопасности, которые вызывают переполнение буфера. Функция StringCbPrintfEx всегда завершает символом конца строки ('\0') целевой буфер ненулевой длины.
StringCbPrintfEx может быть использована в своей унифицированной форме, или в специальной такой как StringCbPrintfExA (для строк ANSI) или StringCbPrintfExW (для строк Unicode). Форма использования определяется Вашими данными.
Тип данных строки |
Литерал строки |
Функция |
|---|---|---|
| char | "string" | StringCbPrintfA |
| TCHAR | TEXT("string") | StringCbPrintf |
| WCHAR | L"string" | StringCbPrintfW |
Функция StringCbPrintfEx и её варианты ANSI и Unicode - замена для этих функций:
Поведение функции не определенное, если строки, указанные при помощи параметров pszDest, pszFormat или любых параметров строк, перекрываются. Ни pszFormat, ни pszDest не должны быть NULL, за исключением того, если это определяется флажком STRSAFE_IGNORE_NULLS, то в этом случае, оба параметра могут быть NULL. Однако, ошибка из-за недостаточного пространства может все еще возвратиться даже при том, что игнорируются нулевые значения.
Обзор Строки, Функции, используемые строками, StringCchPrintf, StringCchPrintfEx, StringCbVPrintfEx
Размещение и совместимость StringCbPrintfEx |
||
| К | 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. | |
| Замечания по платформе | Не имеется | |
