Функция StringCbCopyExA (strsafe.h)

Статья
03/02/2024

Копирует одну строку в другую. Размер целевого буфера предоставляется функции, чтобы гарантировать, что она не записывает данные после конца этого буфера.

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

Одно или несколько из следующих значений.

Значение	Значение
STRSAFE_FILL_BEHIND_NULL 0x00000200	Если функция выполняется успешно, для заполнения неинициализированной части pszDest после завершающего символа NULL используется низкий байт dwFlags (0).
STRSAFE_IGNORE_NULLS 0x00000100	Обрабатывать пустые строковые указатели null (TEXT("")). Этот флаг полезен для эмуляции таких функций, как lstrcpy.
STRSAFE_FILL_ON_FAILURE 0x00000400	Если функция завершается сбоем, для заполнения всего буфера pszDest используется низкий байт dwFlags (0), а буфер завершается со значением NULL. В случае сбоя STRSAFE_E_INSUFFICIENT_BUFFER любая возвращаемая усекаемая строка перезаписывается.
STRSAFE_NULL_ON_FAILURE 0x00000800	Если функция завершается сбоем, pszDest получает пустую строку (TEXT("")). В случае сбоя STRSAFE_E_INSUFFICIENT_BUFFER любая усеченная строка перезаписывается.
STRSAFE_NO_TRUNCATION 0x00001000	Как и в случае STRSAFE_NULL_ON_FAILURE, если функция завершается сбоем, pszDest получает пустую строку (TEXT("")). В случае сбоя STRSAFE_E_INSUFFICIENT_BUFFER любая усеченная строка перезаписывается.

Возвращаемое значение

Тип: HRESULT

Эта функция может возвращать одно из следующих значений. Настоятельно рекомендуется использовать макросы SUCCEEDED и FAILED для проверки возвращаемого значения этой функции.

Код возврата	Описание
S_OK	Исходные данные были полностью скопированы без усечения, а результирующий целевой буфер завершается со значением NULL.
STRSAFE_E_INVALID_PARAMETER	Если есть исходные данные для копирования, pszDest имеет значение NULL , либо был передан недопустимый флаг.
STRSAFE_E_INSUFFICIENT_BUFFER	Операция копирования завершилась сбоем из-за недостаточного пространства в буфере. В зависимости от значения 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

См. также раздел

Справочные материалы

StringCbCopy

StringCchCopyEx

Поделиться через