Функция StringCbCopyN

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

Синтаксис

HRESULT StringCbCopyN(      

    LPTSTR pszDest,
    size_t cbDest,
    LPCTSTR pszSrc,
    size_t cbSrc
);

Параметры

pszDest

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

cbDest

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

pszSrc

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

cbSrc

[in] Максимальное число байтов, которое копируется из pszSrc в pszDest.

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

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

 

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

Описание

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

Замечания

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

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

 

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

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

Функция

char "string" StringCbCopyNA
TCHAR TEXT("string") StringCbCopyN
WCHAR L"string" StringCbCopyNW
 

Не смотря на то, что эта стандартная подпрограмма предполагается как замена функции strncpy, все таки имеются различия в их поведении. Если параметр cbSrc больше, чем число байтов в параметре pszSrc, StringCbCopyN—в отличие strncpyне продолжает дополнять pszDest с нулевыми символами до тех пор, пока не будут скопированы байты cbSrc.

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

Ни pszSrc, ни pszDest не должны быть NULL. См. описание функции StringCbCopyNEx, если требуется обработка значений указателя пустой строки.

Смотри также

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

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

К 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