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

  • Статья

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

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

Синтаксис

STRSAFEAPI StringCbCopyA(
  [out] STRSAFE_LPSTR  pszDest,
  [in]  size_t         cbDest,
  [in]  STRSAFE_LPCSTR pszSrc
);

Параметры

[out] pszDest

Тип: LPTSTR

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

[in] cbDest

Тип: size_t

Размер буфера назначения в байтах. Это значение должно учитывать длину pszSrc плюс завершающий символ NULL. Максимально допустимое число байтов — STRSAFE_MAX_CCH * sizeof(TCHAR).

[in] pszSrc

Тип: LPCTSTR

Указатель на буфер, содержащий исходную строку. Эта исходная строка должна заканчиваться null.

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

Тип: HRESULT

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

Код возврата Описание
S_OK
 Исходные данные были полностью скопированы без усечения, а результирующий буфер назначения завершается null.
STRSAFE_E_INVALID_PARAMETER
 Значение в cbDest меньше sizeof(TCHAR) или больше максимально допустимого значения.
STRSAFE_E_INSUFFICIENT_BUFFER
 Операция копирования завершилась сбоем из-за нехватки места в буфере. Буфер назначения содержит усеченную версию предполагаемого результата, завершаемую null. В ситуациях, когда усечение является приемлемым, это не обязательно может рассматриваться как условие сбоя.
 

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

Комментарии

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

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

Ни pszSrc, ни pszDest не должны иметь значение NULL. Если требуется обработка значений указателя null, см. раздел StringCbCopyEx .

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

Тип данных String Строковый литерал Функция
char Строка StringCbCopyA
TCHAR TEXT("string") StringCbCopy
WCHAR L"string" StringCbCopyW
 

Примечание

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

Требования

Требование Значение
Минимальная версия клиента Windows XP с пакетом обновления 2 (SP2) [классические приложения | Приложения UWP]
Минимальная версия сервера Windows Server 2003 с пакетом обновления 1 (SP1) [классические приложения | Приложения UWP]
Целевая платформа Windows
Header strsafe.h

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

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

StringCbCopyEx

StringCchCopy