Функция StringCbCopyEx

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

Синтаксис

HRESULT StringCbCopyEx(      

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

Параметры

pszDest

[out] Указатель на буфер, который получает скопированную строку.

cbDest

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

pszSrc

[in] Указатель на буфер, содержащий в себе исходную строку. Эта исходная строка должна быть завершена символом конца строки ('\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 Как и в случае STRSAFE_NULL_ON_FAILURE, если функция завершается ошибкой, pszDest устанавливается в пустую строку ( TEXT ("")). В случае сбоя типа STRSAFE_E_INSUFFICIENT_BUFFER поверх записывается любая обрезанная строка.

Возвращаемое значение

Обратите внимание! на то, что функция возвращает значение HRESULT в противоположность функции strcpy, которая возвращает указатель. Поэтому настоятельно рекомендуется, что бы вы использовали макросы SUCCEEDED и FAILED для проверки возвращаемого значения этой функцией.

 

Возвращаемое значение

Описание

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

Замечания

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

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

 

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

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

Функция

char "string" StringCbCopyExA
TCHAR TEXT("string") StringCbCopyEx
WCHAR L"string" StringCbCopyExW
 

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

 

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

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

Смотри также

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

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

К 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