Функция StringCbCatNEx - это замена для функции strncat. Размер целевого буфера, в байтах, передается в функцию, чтобы застраховаться от того, что StringCbCatNEx запишет помимо конца этого буфера. StringCbCatNEx добавляет к функциональным возможностям функции StringCbCatN возвращение указателя на конец строки, являющимся выходным значением, возвращает так же число байтов, оставшееся неиспользованным в этой строке. Для дополнительного управления также могут в функцию передаваться флажки.
HRESULT StringCbCatNEx( LPTSTR pszDest, size_t cbDest, LPCTSTR pszSrc, size_t cbMaxAppend, LPTSTR *ppszDestEnd, size_t *pcbRemaining, DWORD dwFlags ); |
[in, out] Указатель на буфер, содержащий в себе строку, c которой pszSrc объединяется, и который потом содержит всю результирующую строку. Строка в pszSrc добавляется в конец строки в pszDest.
cbDest[in] Размер целевого буфера, в байтах. Это значение должно принимать во внимание длину pszSrc, плюс длину pszDest, плюс байты, используемые символом завершающего нуля. Максимальное дозволенное число байтов вычисляется как STRSAFE_MAX_CCH * sizeof (TCHAR).
pszSrc[in] Указатель на буфер, содержащий в себе исходную строку, которая объединяется до конца с pszDest. Эта исходная строка должна быть завершена символом конца строки ('\0').
cbMaxAppend[in] Максимальное число байтов, добавляемое в конец в pszDest.
ppszDestEnd[out] Адрес указателя на конец pszDest. Если ppszDestEnd не-NULL, и любые данные добавляются в конец в целевом буфере, то он указывает на символ завершающего нуля в конце строки.
pcbRemaining[out] Указатель на переменную, которая указывает число неиспользованных байтов в pszDest, включая и те, которые используются для символа завершающего нуля. Если pcbRemaining - 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 | Значение в cbDest больше, чем STRSAFE_MAX_CCH * sizeof (TCHAR), был передан неправильный флажок, или имеется несоответствие между размерами pszDest, cbDest и количеством данных, которые добавляются в конец в pszSrc.. |
| STRSAFE_E_INSUFFICIENT_BUFFER | Операция копирования завершилась ошибкой из-за недостаточного пространства буфера. В зависимости от значения dwFlags целевой буфер может содержать обрезанную версию с нулевым символом в конце предполагаемого результата ( строки). В ситуациях, где усечение является приемлемым, это может не обязательно быть замечено как условие сбоя. |
Функция StringCbCatNEx предусматривает дополнительную обработку для правильной обработки буфера в вашем коде. Неправильная обработка буфера влечет за собой многие проблемы обеспечения безопасности, которые вызывают переполнение буфера. StringCbCatNEx всегда завершает символом конца строки ('\0') целевой буфер ненулевой длины.
Функция StringCbCatNEx может быть использована в своей унифицированной форме, или специально как StringCbCatNExA (для строк ANSI) или StringCbCatNExW (для строк Unicode). Форма использования определяется вашими данными.
Тип данных строки |
Литерал строки |
Функция |
|---|---|---|
| char | "string" | StringCbCatNExA |
| TCHAR | TEXT("string") | StringCbCatNEx |
| WCHAR | L"string" | StringCbCatNExW |
Функция StringCbCatNEx и ёе варианты ANSI и Unicode являются заменой для этих функций:
Поведение функции неопределенное, если строки указанные параметрами pszSrc и pszDest частично перекрываются.
Ни pszSrc, ни pszDest не должны быть NULL. См. описание функции StringCbCatEx, если вам требуется обработка значений указателя пустой строки.
Ни pszSrc, ни pszDest не должны быть NULL, если флажок STRSAFE_IGNORE_NULLS не определяется, при котором в этом случае, оба параметра могут быть NULL. Однако, ошибка из-за недостаточного пространства может все еще возвратиться даже при том, что игнорируются нулевые (пустые) значения.
Обзор Строки, Функции, используемые строками, StringCchCatNEx, StringCbCatEx, StringCbCatN
|
Размещение и совместимость StringCbCatNEx |
||
| К | 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. | |
| Замечания по платформе | Не имеется | |
