Функция StringCbCopyNW (strsafe.h)
Копирует указанное количество байтов из одной строки в другую. Размер целевого буфера предоставляется функции, чтобы гарантировать, что она не записывает данные после конца этого буфера.
StringCbCopyN является заменой следующих функций:
Синтаксис
STRSAFEAPI StringCbCopyNW(
[out] STRSAFE_LPWSTR pszDest,
[in] size_t cbDest,
[in] STRSAFE_PCNZWCH pszSrc,
[in] size_t cbToCopy
);
Параметры
[out] pszDest
Тип: LPTSTR
Буфер назначения, который получает скопированные символы.
[in] cbDest
Тип: size_t
Размер pszDest в байтах. Это значение должно быть достаточно большим, чтобы вместить скопированные байты (размер pszSrc или значение cbSrc, в зависимости от того, что меньше), а также учитывать завершающий символ NULL. Максимально допустимое количество символов — STRSAFE_MAX_CCH * sizeof(TCHAR).
[in] pszSrc
Тип: LPCTSTR
Исходная строка. Эта строка должна заканчиваться null.
[in] cbToCopy
Тип: size_t
Максимальное число байтов, копируемых из pszSrc в pszDest.
Возвращаемое значение
Тип: HRESULT
Эта функция может возвращать одно из следующих значений. Настоятельно рекомендуется использовать макросы SUCCEEDED и FAILED для проверки возвращаемого значения этой функции.
| Код возврата | Описание |
|---|---|
|
Исходные данные присутствовали, данные были скопированы из pszSrc без усечения, а результирующий буфер назначения завершается со значением NULL. |
|
Значение в cbDest больше, чем STRSAFE_MAX_CCH * sizeof(TCHAR), или целевой буфер уже заполнен.
|
|
Операция копирования завершилась сбоем из-за недостаточного пространства в буфере. Целевой буфер содержит усеченную версию предполагаемого результата, завершаемую null. В ситуациях, когда усечение приемлемо, это не обязательно может рассматриваться как условие сбоя. |
Обратите внимание, что эта функция возвращает значение HRESULT , в отличие от функций, которые она заменяет.
Комментарии
StringCbCopyN обеспечивает дополнительную обработку для правильной обработки буфера в коде. Плохая обработка буфера связана со многими проблемами безопасности, которые связаны с переполнением буфера. StringCbCopyN всегда завершается со значением NULL и никогда не переполняет допустимый буфер назначения, даже если содержимое исходной строки изменяется во время операции.
Хотя эта подпрограмма предназначена для замены strncpy, существуют различия в поведении. Если cbSrc больше, чем число байтов в pszSrc, StringCbCopyN, в отличие от strncpy, не будет добавлять в pszDest символы NULL, пока не будут скопированы байты cbSrc .
Поведение не определено, если строки, на которые указывают pszSrc и pszDest , перекрываются.
Ни pszSrc, ни pszDest не должны иметь значение NULL. См . раздел StringCbCopyNEx , если требуется обработка значений строкового указателя null.
StringCbCopyN можно использовать в универсальной форме или в более конкретных формах. Тип данных строки определяет форму этой функции, которую следует использовать, как показано в следующей таблице.
| Тип данных String | Строковый литерал | Функция |
|---|---|---|
| char | Строка | StringCbCopyNA |
| TCHAR | TEXT("string") | StringCbCopyN |
| WCHAR | L"string" | StringCbCopyNW |
Примечание
Заголовок strsafe.h определяет StringCbCopyN в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Минимальная версия клиента | Windows XP с пакетом обновления 2 (SP2) [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows Server 2003 с пакетом обновления 1 (SP1) [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | strsafe.h |
См. также раздел
Справочные материалы