Функция StringCbCopyN - это замена для функции strncpy. StringCbCopyN копирует заданное число байтов из исходной строки. Размер, в байтах, целевого буфера передается в функцию, чтобы гарантировать, что StringCbCopyN не запишет помимо конца этого буфера.
HRESULT StringCbCopyN( LPTSTR pszDest, size_t cbDest, LPCTSTR pszSrc, size_t cbSrc ); |
[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. | |
| Замечания по платформе | Не имеется | |
