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

Статья
11/20/2024

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

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

strncpy, wcsncpy, _tcsncpy

Синтаксис

STRSAFEAPI StringCchCopyNA(
  [out] STRSAFE_LPSTR  pszDest,
  [in]  size_t         cchDest,
  [in]  STRSAFE_PCNZCH pszSrc,
  [in]  size_t         cchToCopy
);

Параметры

[out] pszDest

Тип: LPTSTR

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

[in] cchDest

Тип: size_t

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

[in] pszSrc

Тип: LPCTSTR

Исходная строка. Эта строка должна быть доступной для чтения до символов cchSrc или конца null, в зависимости от того, что происходит в первую очередь.

[in] cchToCopy

Тип: size_t

Максимальное количество символов, скопированных из pszSrc в pszDest.

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

Тип: HRESULT

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

Возвращаемый код	Описание
S_OK	Исходные данные были представлены, символы были скопированы из pszSrc без усечения, а результирующий целевой буфер завершается значением NULL.
STRSAFE_E_INVALID_PARAMETER	Значение в cchDest больше, чем STRSAFE_MAX_CCH, или целевой буфер уже заполнен.
STRSAFE_E_INSUFFICIENT_BUFFER	Операция копирования завершилась ошибкой из-за нехватки буферного пространства. Целевой буфер содержит усеченную, завершаемую null версию предполагаемого результата. В ситуациях, когда усечение приемлемо, это может не обязательно рассматриваться как условие сбоя.

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

Замечания

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

Хотя эта подпрограмма предназначена в качестве замены strncpy, существуют различия в поведении. Если cchSrc больше количества символов в pszSrc, StringCchCopyN—в отличие от strncpy— не продолжает pszDest с пустыми символами до тех пор, пока cchSrc символы не будут скопированы.

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

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

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

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

Заметка

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

Требования

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

См. также

Справочник

StringCbCopyN

StringCchCopy

StringCchCopyNEx

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