Функция StringCbCopyNEx

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

Синтаксис

HRESULT StringCbCopyNEx(      

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

Параметры

pszDest

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

cbDest

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

pszSrc

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

cbSrc

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

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

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

 

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

Описание

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

Замечания

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

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

 

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

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

Функция

char "string" StringCbCopyNExA
TCHAR TEXT("string") StringCbCopyNEx
WCHAR L"string" StringCbCopyNExW

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

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

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

Смотри также

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

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

К 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