Функция StringCchCopyN - замена функции strncpy. StringCchCopyN копирует заданное число символов из исходной строки. Размер, в символах, целевого буфера назначается в функцию для того, чтобы гарантировать, что StringCchCopyN не запишет помимо конца этого буфера.
HRESULT StringCchCopyN( LPTSTR pszDest, size_t cchDest, LPCTSTR pszSrc, size_t cchSrc ); |
[out] Указатель на буфер, который получает скопированные символы.
cchDest[in] Размер pszDest, в символах. Это значение должно быть достаточно большим, чтобы содержать скопированные символы (длина pszSrc или значение cchSrc, который меньше) плюс 1, чтобы принять во внимание символ завершающего нуля. Максимальное число допустимых символов является STRSAFE_MAX_CCH.
pszSrc[in] Указатель на буфер, содержащий исходную строку. Эта исходная строка должна быть завершена символом конца строки ('\0').
cchSrc[in] Максимальное число символов для копирования из pszSrc в pszDest.
 Обратите внимание! на то, что функцией возвращается значение HRESULT в противоположность функции
strncpy, которая возвращает указатель. Поэтому настоятельно рекомендуется, чтобы вы использовали макросы SUCCEEDED и
FAILED для проверки возвращаемого значения этой функцией. |
Значение |
Предназначение |
| S_OK | Исходные данные присутствовали, символы копировались из pszSrc без усечения, а итоговый результат целевого буфера завершен символом конца строки ('\0'). |
| STRSAFE_E_INVALID_PARAMETER | Значение в cchDest или больше, чем STRSAFE_MAX_CCH, или целевой буфер уже заполнен. |
| STRSAFE_E_INSUFFICIENT_BUFFER | Операция копирования завершалась ошибкой из-за недостаточного места в буфере. Целевой буфер содержит обрезанную версию с нулевым символом в конце предполагаемого результата. В ситуациях, где усечение является приемлемым, это может не обязательно быть отмечено как условие сбоя. |
Функция StringCchCopyN предусматривает дополнительную обработку для правильной работы буфера в Вашем коде. Недостаточная обработка буфера влечет за собой многие проблемы обеспечения безопасности, которые вызывают переполнение буфера. StringCchCopyN всегда завершает символом конца строки ('\0') целевой буфер ненулевой длины.
Функция StringCchCopyN может быть использована в её общей форме, или в специальной типа StringCchCopyNA (для строк ANSI) или StringCchCopyNW (для строк Unicode). Форма использования определяется Вашими данными.
Тип строковых данных |
Строковый литерал |
Функция |
|---|---|---|
| char | "string" | StringCchCopyNA |
| TCHAR | TEXT("string") | StringCchCopyN |
| WCHAR | L"string" | StringCchCopyNW |
Наряду с тем, что эта процедура предназначается как замена для strncpy, есть различия в их поведении. Если cchSrc больше, чем число символов в pszSrc, StringCchCopyN, в отличие от strncpy, не продолжает дополнять pszDest нулевыми символами до тех пор, пока символы cchSrc не скопируются.
Поведение становится неопределенным, если строки указанные при помощи параметров pszSrc и pszDest - перекрываются.
Ни pszSrc, ни pszDest не должны быть NULL. См. StringCchCopyNEx, если требуется обработка значений указателя пустой строки.
Обзор Строки, Функции, используемые строками, StringCbCopyN, StringCchCopyNEx, StringCchCopy
Размещение и совместимость StringCchCopyN |
||
| К | 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. | |
| Замечания по платформе | Не имеется | |
