Функция StringCchCatEx

Функция StringCchCatEx - это замена для функции strcat. Размер, в символах, целевого буфера назначается в функцию, чтобы гарантировать, что StringCchCatEx не запишет помимо конца этого буфера. StringCchCatEx добавляет к функциональным возможностям функции StringCchCat, возвращение указателя на конец строки, являющаяся выходным значением, а так же число символов оставшееся неиспользованными в этой строке. В функцию для дополнительного управления могут также передаваться флажки.

Синтаксис

HRESULT StringCchCatEx(      

    LPTSTR pszDest,
    size_t cchDest,
    LPCTSTR pszSrc,
    LPTSTR *ppszDestEnd,
    size_t *pcchRemaining,
    DWORD dwFlags
);

Параметры

pszDest

[in, out] Указатель на буфер, содержащий строку, c которой pszSrc объединяется, и который содержит в себе всю результирующую строку. Строка в pszSrc добавляется в конец строки в pszDest.

cchDest

[in] Размер целевого буфера, в символах. Это значение должно равняться длине pszSrc плюс длина pszDest плюс 1, чтобы учесть обе строки и символ завершающего нуля. Максимальное число символов допускается STRSAFE_MAX_CCH.

pszSrc

[in] Указатель на буфер, содержащий исходную строку, которая объединяется до конца pszDest. Эта исходная строка должна быть завершена символом конца строки ('\0').

ppszDestEnd

[out] Адрес указателя на конец pszDest. Если ppszDestEnd не-NULL, и какие-либо данные добавляются в конец целевого буфера, он указывает на символ завершающего нуля в конце строки.

pcchRemaining

[out] Указатель на переменную, который указывает число неиспользуемых символов в pszDest, включая символ завершающего нуля. Если pcchRemaining - NULL, подсчет не сохраняется или возвращается (значение).

dwFlags

[in] Используется одно или несколько из нижеследующих значений.

Флажок

Предназначение

STRSAFE_FILL_BEHIND_NULL Если функция завершается успешно, младший байт dwFlags (0) используется, чтобы заполнить неинициализированную часть pszDest после символа завершающего нуля.
STRSAFE_IGNORE_NULLS Обрабатывает указатели пустой строки подобно пустым строкам ( TEXT ("")). Этот флажок полезен для эмуляции функций такой как lstrcpy.
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 в противоположность функции strcat, которая возвращает указатель. Поэтому настоятельно рекомендуется, чтобы вы использовали макросы SUCCEEDED и FAILED для проверки возвращаемого значения этой функцией.


 

Значение

Предназначение

S_OK Исходные данные присутствовали, строки были полностью объединены без усечения, а итоговый результат целевого буфера завершен символом конца строки ('\0').
STRSAFE_E_INVALID_PARAMETER Значение в cchDest или 0, или больше чем STRSAFE_MAX_CCH, или целевой буфер уже заполнен.
STRSAFE_E_INSUFFICIENT_BUFFER Операция копирования завершалась ошибкой из-за недостаточного пространства буфера. В зависимости от значения dwFlags, целевой буфер может содержать обрезанную версию с нулевым символом в конце предполагаемого результата. В ситуациях, где усечение является приемлемым, это не обязательно может быть отмечено как условие сбоя.

Замечания

Функция StringCchCatEx предусматривает дополнительную обработку для правильной работы буфера в Вашем коде. Недостаточная обработка буфера влечется за собой многие проблемы обеспечения безопасности, которые вызывают переполнение буфера. StringCchCatEx всегда завершает символом конца строки ('\0') целевой буфер ненулевой длины.

Функция StringCchCatEx может использоваться в своей общей форме, или в специальной, типа StringCchCatExA (для строк ANSI) или StringCchCatExW (для строк Unicode). Форма использования определяется Вашими данными.

Тип строковых данных

Строковый литерал

Функция

char "string" StringCchCatExA
TCHAR TEXT("string") StringCchCatEx
WCHAR L"string" StringCchCatExW

Функция StringCchCatEx и её варианты ANSI и Unicode - замена для этих функций:

Поведение неопределенное, если строки указанные при помощи pszSrc и pszDest перекрываются.

Ни pszSrc, ни pszDest не должны быть NULL, если не определяется флажок STRSAFE_IGNORE_NULLS , при котором в этом случае, оба параметра могут быть NULL. Однако, ошибка, из-за недостаточного пространства, может все еще возвратиться даже при том, что игнорируются нулевые значения.

Смотри также

Обзор Строки, Функции, используемые строками, StringCchCat, StringCbCatEx, StringCchCatNEx

Размещение и совместимость StringCchCatEx

К 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.
Замечания по платформе Не имеется
Назад в оглавление
На главную страницу
В оглавление справки

Hosted by uCoz