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