Функция StringCbCatEx

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

Синтаксис

HRESULT StringCbCatEx(      

    LPTSTR pszDest,
    size_t cbDest,
    LPCTSTR pszSrc,
    LPTSTR *ppszDestEnd,
    size_t *pcbRemaining,
    DWORD dwFlags
);

Параметры

pszDest

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

cbDest

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

pszSrc

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

ppszDestEnd

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

pcbRemaining

[out] Указатель на переменную, которая указывает число неиспользованных байтов в pszDest, включая и те, которое используется для символа завершающего нуля. Если pcbRemaining 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 Значение в cbDest или 0, или больше, чем STRSAFE_MAX_CCH * sizeof (TCHAR), или целевой буфер уже заполнен.
STRSAFE_E_INSUFFICIENT_BUFFER Операция копирования завершалась ошибкой из-за недостаточного пространства буфера. В зависимости от значения dwFlags, целевой буфер может содержать обрезанную версию с нулевым символом в конце предполагаемого результата ( строки). В ситуациях, где усечение является приемлемым, это может не обязательно быть замечено как условие сбоя.

Замечания

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

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

 

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

Литерал строки

Функция

char "string" StringCbCatExA
TCHAR TEXT("string") StringCbCatEx
WCHAR L"string" StringCbCatExW

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

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

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

Смотри также

Обзор Строки, Функции, используемые строками, StringCbCat, StringCchCatEx, StringCbCatNEx

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

К 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