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