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

Статья
11/20/2024

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

StringCchCopyEx добавляет к функциям StringCchCopy, возвращая указатель на конец конечной строки, а также количество символов, оставшихся неиспользуемыми в этой строке. Флаги также могут передаваться этой функции для дополнительного элемента управления.

StringCchCopyEx является заменой следующих функций:

Синтаксис

STRSAFEAPI StringCchCopyExA(
  [out]           STRSAFE_LPSTR  pszDest,
  [in]            size_t         cchDest,
  [in]            STRSAFE_LPCSTR pszSrc,
  [out, optional] STRSAFE_LPSTR  *ppszDestEnd,
  [out, optional] size_t         *pcchRemaining,
  [in]            DWORD          dwFlags
);

Параметры

[out] pszDest

Тип: LPTSTR

Целевой буфер, который получает скопированную строку.

[in] cchDest

Тип: size_t

Размер целевого буфера в символах. Это значение должно иметь длину pszSrc плюс 1, чтобы учитывать скопированную исходную строку и завершающий символ NULL. Максимально допустимое число символов — STRSAFE_MAX_CCH.

[in] pszSrc

Тип: LPCTSTR

Исходная строка. Эта строка должна быть завершена значением NULL.

[out, optional] ppszDestEnd

Тип: LPTSTR*

Адрес указателя на конец pszDest. Если ppszDestEnd не являетсяNULL, а все данные копируются в целевой буфер, это указывает на конечный символ NULL в конце строки.

[out, optional] pcchRemaining

Тип: size_t*

Количество неиспользуемых символов в pszDest, включая завершающийся символ NULL. Если pcchRemainingNULL, количество не сохраняется или возвращается.

[in] dwFlags

Тип: DWORD

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

Ценность	Значение
STRSAFE_FILL_BEHIND_NULL 0x00000200	Если функция выполнена успешно, используется низкий байт dwFlags (0) для заполнения неинициализированной части pszDest после конца символа NULL.
STRSAFE_IGNORE_NULLS 0x00000100	Обработайте значений NULL строк, таких как пустые строки (TEXT("")). Этот флаг полезен для эмулирования таких функций, как lstrcpy.
STRSAFE_FILL_ON_FAILURE 0x00000400	Если функция завершается ошибкой, используется низкий байт dwFlags (0) для заполнения всего буфера pszDest, а буфер завершается значением 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	Либо pszDestNULL при наличии исходных данных для копирования, либо был передан недопустимый флаг.
STRSAFE_E_INSUFFICIENT_BUFFER	Операция копирования завершилась ошибкой из-за нехватки буферного пространства. В зависимости от значения dwFlags, целевой буфер может содержать усеченную, завершаемую null версию предполагаемого результата. В ситуациях, когда усечение приемлемо, это может не обязательно рассматриваться как условие сбоя.

Обратите внимание, что эта функция возвращает значение HRESULT, в отличие от функций, которые он заменяет.

Замечания

По сравнению с функциями, которые он заменяет, StringCchCopyEx обеспечивает дополнительную обработку буфера в коде. Низкая обработка буфера связана со многими проблемами безопасности, включающими переполнение буфера. StringCchCopyEx всегда завершает значение NULL и никогда не переполняет допустимый целевой буфер, даже если содержимое исходной строки изменяется во время операции.

Поведение не определено, если строки, на которые указывает pszSrc и pszDest перекрываются.

Ни pszSrc, ни pszDest не должны быть NULL, если только флаг STRSAFE_IGNORE_NULLS не указан, в этом случае оба параметра могут быть NULL. Однако ошибка из-за нехватки места может быть возвращена, даже если значения NULL игнорируются.

StringCchCopyEx можно использовать в универсальной форме или в более конкретных формах. Тип данных строки определяет форму этой функции, которую следует использовать.

Тип данных строки	Строковый литерал	Функция
char	"string"	StringCchCopyExA
TCHAR	TEXT("string")	StringCchCopyEx
WCHAR	L"string"	StringCchCopyExW

Заметка

Заголовок strsafe.h определяет StringCchCopyEx как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP с пакетом обновления 2 (SP2) [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2003 с пакетом обновления 1 (SP1) [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	strsafe.h

См. также

Справочник

StringCbCopyEx

StringCchCopy

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