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