Функция StringCchPrintfEx - это замена функции sprintf. Она принимает форматирующую строку и список параметров и возвращает отформатированную строку. Размер, в символах, целевого буфера назначается в функцию для того, чтобы гарантировать, что StringCchPrintfEx не запишет помимо конца этого буфера. Функция StringCchPrintfEx добавляет к функциональным возможностям StringCchPrintf возвращение указателя на конец строки, являющейся выходным значением, а так же числа символов, оставшееся неиспользуемым в этой строке. В функцию, для дополнительного управления, могут также передаваться флажки.
HRESULT StringCchPrintfEx( LPTSTR pszDest, size_t cchDest, LPTSTR *ppszDestEnd, size_t *pcchRemaining, DWORD dwFlags, LPCTSTR pszFormat, ... ); |
[out] Указатель на буфер, который получает отформатированную строку с завершающим нулем, созданную из pszFormat и его параметров.
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, любая обрезанная строка перезаписывается. |
pszFormat
[in] Указатель на буфер, содержащий форматирующую строку printf-стиля. Эта строка должна быть завершена символом конца строки ('\0')....
[in] Параметры, которые будут вставлены в pszFormat. Обратите внимание! на то, что эта функция возвращает HRESULT в противоположность функции
sprintf, которая возвращает число байтов, сохраненных в целевом буфере. Настоятельно рекомендуется использовать макроопределения
SUCCEEDED и FAILED, чтобы проверить возвращаемое значение этой функцией. |
Значение |
Предназначение |
| S_OK | Было достаточное место для результата копирования pszDest без усечения, а буфер завершен символом конца строки ('\0'). |
| STRSAFE_E_INVALID_PARAMETER | Значение в cchDest или 0, или больше, чем STRSAFE_MAX_CCH, или целевой буфер уже заполнен. |
| STRSAFE_E_INSUFFICIENT_BUFFER | Операция копирования завершалась ошибкой из-за недостаточного места в буфере. В зависимости от значения dwFlags, целевой буфер может содержать обрезанную версию с нулевым символом в конце предполагаемого результата. В ситуациях, где усечение является приемлемым, это может не обязательно быть отмечено как условие сбоя. |
Функция StringCchPrintfEx предусматривает дополнительную обработку для правильной работы буфера в Вашем коде. Недостаточная обработка буфера влечет за собой многие проблемы обеспечения безопасности, которые вызывают переполнение буфера. StringCchPrintfEx всегда завершает символом конца строки ('\0') целевой буфер ненулевой длины.
Функция StringCchPrintfEx может быть использована в своей общей форме или в спецальной, такой как StringCchPrintfExA (для строк ANSI) или StringCchPrintfExW (для строк Unicode. Форма использования определяется Вашими данными.
Тип строковых данных |
Строковый литерал |
Функция |
|---|---|---|
| char | "string" | StringCchPrintfExA |
| TCHAR | TEXT("string") | StringCchPrintfEx |
| WCHAR | L"string" | StringCchPrintfExW |
Функция StringCchPrintfEx и её ANSI и Unicode варианты - заменяют эти функции:
Поведение не определяется, если строки указанные при помощи pszDest, pszFormat, или какие-либо параметры строк перекрываются.
Ни pszFormat, ни pszDest не должны быть NULL, если не определяется флажок STRSAFE_IGNORE_NULLS, при котором в этом случае, оба параметра могут быть NULL. Однако, ошибка из-за недостаточного места может все еще возвратиться даже при том, что игнорируются нулевые значения.
Обзор Строки, Функции, используемые строками, StringCbPrintfEx, StringCchPrintf, StringCchVPrintfEx
Размещение и совместимость StringCchPrintfEx |
||
| К | 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. | |
| Замечания по платформе | Не имеется | |
