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