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