Функция StringCchCat - это замена функции strcat. Размер, в символах, целевого буфера назначается в функцию для того, чтобы гарантировать, что StringCchCat не запишет мимо конца этого буфера.
HRESULT StringCchCat( LPTSTR pszDest, size_t cchDest, LPCTSTR pszSrc ); |
[in, out] Указатель на буфер, содержащий в себе строку, c которой строка pszSrc объединяется, и который содержит всю результирующую строку. Строка в pszSrc добавляется в конец строки в pszDest.
cchDest[in] Размер целевого буфера, в символах. Это значение должно равняться длине pszSrc, плюс длина pszDest плюс 1, чтобы учесть длину обеих строк и символ завершающего нуля. Максимальное число символов допускается до STRSAFE_MAX_CCH.
pszSrc[in] Указатель на буфер, содержащий в себе исходную строку, которая объединяется до конца pszDest. Эта исходная строка должна быть завершена символом конца строки ('\0').
 Обратите внимание! на то, что функцией
возвращается значение HRESULT в противоположность функции
strcat, которая возвращает указатель. Поэтому настоятельно рекомендуется, чтобы вы использовали макросы SUCCEEDED и
FAILED для проверки возвращаемого значения этой функцией. |
Значение |
Предназначение |
| S_OK | Исходные данные присутствовали, строки были полностью объединены без усечения и итоговый результат целевого буфера завершен символом конца строки ('\0'). |
| STRSAFE_E_INVALID_PARAMETER | Значение в cchDest или 0 или больше, а не STRSAFE_MAX_CCH, или целевой буфер уже заполнен. |
| STRSAFE_E_INSUFFICIENT_BUFFER | Операция конкатенации завершалась ошибкой из-за недостаточного пространства буфера. Целевой буфер содержит обрезанную версию с нулевым символом в конце предполагаемого результата. В ситуациях, где усечение является приемлемым, это может не обязательно быть замечено как условие сбоя. |
Функция StringCchCat предусматривает дополнительную обработку для правильной работы буфера в Вашем коде. Недостаточная обработка буфера влечет за собой многие проблемы обеспечения безопасности, которые вызывают переполнение буфера. StringCchCat всегда завершает символом конца строки ('\0') целевой буфер ненулевой длины.
StringCchCat может использоваться в своей общей форме, или в специальной, такой как StringCchCatA (для строк ANSI) или StringCchCatW (для строк Unicode). Форма использования определяется Вашими данными.
Тип данных строки |
Литерал строки |
Функция |
|---|---|---|
| char | "string" | StringCchCatA |
| TCHAR | TEXT("string") | StringCchCat |
| WCHAR | L"string" | StringCchCatW |
Функция StringCchCat и её варианты ANSI и Unicode - замена для этих функций:
Поведение неопределенное, если строки указанные при помощи pszSrc и pszDest - перекрываются.
Ни pszSrc, ни pszDest не должны быть NULL. См. описание StringCchCatEx, если Вам потребуется обработка значений указателя пустой строки.
Обзор Строки, Функции, используемые строками, StringCbCat, StringCchCatEx, StringCchCatN
Размещение и совместимость StringCchCat |
||
| К | 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. | |
| Замечания по платформе | Не имеется | |
