Функция StringCchCopyNExW (strsafe.h)
Копирует указанное количество символов из одной строки в другую. Размер буфера назначения предоставляется функции, чтобы гарантировать, что она не будет записывать данные после конца этого буфера.
StringCchCopyNEx добавляет к функциональным возможностям StringCchCopyN , возвращая указатель на конец строки назначения, а также количество символов, оставшихся неиспользуемыми в этой строке. Флаги также могут передаваться в функцию для дополнительного управления.
StringCchCopyNEx заменяет следующие функции:
Синтаксис
STRSAFEAPI StringCchCopyNExW(
[out] STRSAFE_LPWSTR pszDest,
[in] size_t cchDest,
[in] STRSAFE_PCNZWCH pszSrc,
[in] size_t cchToCopy,
[out, optional] STRSAFE_LPWSTR *ppszDestEnd,
[out, optional] size_t *pcchRemaining,
[in] DWORD dwFlags
);
Параметры
[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.
[out, optional] ppszDestEnd
Тип: LPTSTR*
Адрес указателя на конец pszDest. Если параметр ppszDestEnd не равен NULL и какие-либо данные копируются в буфер назначения, это указывает на завершающий символ NULL в конце строки.
[out, optional] pcchRemaining
Тип: size_t*
Количество неиспользуемых символов в pszDest, включая завершающий пустой символ. Если pcchRemaining имеет значение NULL, счетчик не сохраняется и не возвращается.
[in] dwFlags
Тип: DWORD
Одно или несколько из следующих значений.
Возвращаемое значение
Тип: HRESULT
Эта функция может возвращать одно из следующих значений. Настоятельно рекомендуется использовать макросы SUCCEEDED и FAILED для проверки возвращаемого значения этой функции.
| Код возврата | Описание |
|---|---|
|
Исходные данные были полностью скопированы без усечения, а результирующий буфер назначения завершается null. |
|
PszDest или pszSrc больше STRSAFE_MAX_CCH, pszDest имеет значение NULL при наличии исходных данных для копирования или передаче недопустимого флага. |
|
Операция копирования завершилась сбоем из-за нехватки места в буфере. В зависимости от значения dwFlags, буфер назначения может содержать усеченную версию предполагаемого результата, завершаемую null. В ситуациях, когда усечение является приемлемым, это не обязательно может рассматриваться как условие сбоя. |
Обратите внимание, что эта функция возвращает значение HRESULT , в отличие от функций, которые она заменяет.
Комментарии
StringCchCopyNEx обеспечивает дополнительную обработку для правильной обработки буфера в коде. Плохая обработка буфера связана со многими проблемами безопасности, которые связаны с переполнением буфера. StringCchCopyNEx всегда завершается со значением NULL и никогда не переполняет допустимый буфер назначения, даже если содержимое исходной строки изменяется во время операции.
Хотя эта процедура предназначена для замены strncpy, существуют различия в поведении. Если значение cchSrc больше числа символов в pszSrc, StringCchCopyNEx , в отличие от strncpy, не будет добавлять в pszDest пустые символы, пока не будут скопированы символы cchSrc .
Поведение не определено, если строки, на которые указывают pszSrc и pszDest , перекрываются.
Ни pszSrc, ни pszDest не должны иметь значение NULL , если не указан флаг STRSAFE_IGNORE_NULLS . В этом случае оба значения могут иметь значение NULL. Однако ошибка из-за нехватки места может по-прежнему возвращаться, даже если значения NULL игнорируются.
StringCchCopyNEx можно использовать в его универсальной форме или в более конкретных формах. Тип данных строки определяет форму этой функции, которую следует использовать, как показано в следующей таблице.
| Тип данных String | Строковый литерал | Функция |
|---|---|---|
| char | Строка | StringCchCopyNExA |
| TCHAR | TEXT("string") | StringCchCopyNEx |
| WCHAR | L"string" | StringCchCopyNExW |
Примечание
Заголовок strsafe.h определяет StringCchCopyNEx в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows XP с пакетом обновления 2 (SP2) [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows Server 2003 с пакетом обновления 1 (SP1) [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | strsafe.h |
См. также раздел
Справочные материалы