Функция StringCbCopyExA (strsafe.h)
Копирует одну строку в другую. Размер целевого буфера предоставляется функции, чтобы гарантировать, что она не записывает данные после конца этого буфера.
StringCbCopyEx добавляет к функциональным возможностям StringCbCopy , возвращая указатель на конец конечной строки, а также количество байтов, оставшихся в этой строке. Флаги также могут передаваться в функцию для дополнительного управления.
StringCbCopyEx является заменой следующих функций:
Синтаксис
STRSAFEAPI StringCbCopyExA(
[out] STRSAFE_LPSTR pszDest,
[in] size_t cbDest,
[in] STRSAFE_LPCSTR pszSrc,
[out, optional] STRSAFE_LPSTR *ppszDestEnd,
[out, optional] size_t *pcbRemaining,
[in] DWORD dwFlags
);
Параметры
[out] pszDest
Тип: LPTSTR
Буфер назначения, который получает скопированную строку.
[in] cbDest
Тип: size_t
Размер целевого буфера в байтах. Это значение должно учитывать длину pszSrc плюс завершающий символ NULL. Максимально допустимое количество байтов — STRSAFE_MAX_CCH * sizeof(TCHAR).
[in] pszSrc
Тип: LPCTSTR
Исходная строка. Эта строка должна заканчиваться null.
[out, optional] ppszDestEnd
Тип: LPTSTR*
Адрес указателя на конец pszDest. Если значение ppszDestEnd не равно NULL и все данные копируются в буфер назначения, это указывает на завершающий символ NULL в конце строки.
[out, optional] pcbRemaining
Тип: size_t*
Количество неиспользуемых байтов в pszDest, включая байты, используемые для завершающего символа NULL. Если pcbRemaining имеет значение NULL, счетчик не сохраняется и не возвращается.
[in] dwFlags
Тип: DWORD
Одно или несколько из следующих значений.
| Значение | Значение |
|---|---|
|
Если функция выполняется успешно, для заполнения неинициализированной части pszDest после завершающего символа NULL используется низкий байт dwFlags (0). |
|
Обрабатывать пустые строковые указатели null (TEXT("")). Этот флаг полезен для эмуляции таких функций, как lstrcpy. |
|
Если функция завершается сбоем, для заполнения всего буфера pszDest используется низкий байт dwFlags (0), а буфер завершается со значением NULL. В случае сбоя STRSAFE_E_INSUFFICIENT_BUFFER любая возвращаемая усекаемая строка перезаписывается. |
|
Если функция завершается сбоем, pszDest получает пустую строку (TEXT("")). В случае сбоя STRSAFE_E_INSUFFICIENT_BUFFER любая усеченная строка перезаписывается. |
|
Как и в случае STRSAFE_NULL_ON_FAILURE, если функция завершается сбоем, pszDest получает пустую строку (TEXT("")). В случае сбоя STRSAFE_E_INSUFFICIENT_BUFFER любая усеченная строка перезаписывается. |
Возвращаемое значение
Тип: HRESULT
Эта функция может возвращать одно из следующих значений. Настоятельно рекомендуется использовать макросы SUCCEEDED и FAILED для проверки возвращаемого значения этой функции.
| Код возврата | Описание |
|---|---|
|
Исходные данные были полностью скопированы без усечения, а результирующий целевой буфер завершается со значением NULL. |
|
Если есть исходные данные для копирования, pszDest имеет значение NULL , либо был передан недопустимый флаг. |
|
Операция копирования завершилась сбоем из-за недостаточного пространства в буфере. В зависимости от значения dwFlags буфер назначения может содержать усеченную версию предполагаемого результата, завершаемую null. В ситуациях, когда усечение приемлемо, это не обязательно может рассматриваться как условие сбоя. |
Обратите внимание, что эта функция возвращает значение HRESULT , в отличие от функций, которые она заменяет.
Комментарии
По сравнению с функциями, которые он заменяет, StringCbCopyEx обеспечивает дополнительную обработку для правильной обработки буфера в коде. Плохая обработка буфера связана со многими проблемами безопасности, которые связаны с переполнением буфера. StringCbCopyEx всегда завершается со значением NULL и никогда не переполняет допустимый буфер назначения, даже если содержимое исходной строки изменяется во время операции.
Поведение не определено, если строки, на которые указывают pszSrc и pszDest , перекрываются.
Ни pszSrc, ни pszDest не должны иметь значение NULL , если не указан флаг STRSAFE_IGNORE_NULLS . В этом случае оба параметра могут иметь значение NULL. Однако ошибка из-за нехватки места может по-прежнему возвращаться, даже если значения NULL игнорируются.
StringCbCopyEx можно использовать в универсальной форме или в более конкретных формах. Тип данных строки определяет форму этой функции, которую следует использовать.
| Тип данных String | Строковый литерал | Функция |
|---|---|---|
| char | Строка | StringCbCopyExA |
| TCHAR | TEXT("string") | StringCbCopyEx |
| WCHAR | L"string" | StringCbCopyExW |
Примечание
Заголовок strsafe.h определяет StringCbCopyEx как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows XP с пакетом обновления 2 (SP2) [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows Server 2003 с пакетом обновления 1 (SP1) [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | strsafe.h |
См. также раздел
Справочные материалы