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

Статья
03/02/2024

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

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

strncpy, wcsncpy, _tcsncpy

Синтаксис

STRSAFEAPI StringCchCopyNW(
  [out] STRSAFE_LPWSTR  pszDest,
  [in]  size_t          cchDest,
  [in]  STRSAFE_PCNZWCH 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, не будет добавлять символы NULL в pszDest до тех пор, пока не будут скопированы символы cchSrc .

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

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

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

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

Примечание

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

Требования

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

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

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

StringCbCopyN

StringCchCopy

StringCchCopyNEx