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

Статья
11/20/2024

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

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

strncpy, wcsncpy, _tcsncpy

Синтаксис

STRSAFEAPI StringCbCopyNA(
  [out] STRSAFE_LPSTR  pszDest,
  [in]  size_t         cbDest,
  [in]  STRSAFE_PCNZCH 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 макросы для проверки возвращаемого значения этой функции.

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

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

Замечания

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

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

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

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

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

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

Заметка

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

Требования

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

См. также

Справочник

StringCbCopy

StringCbCopyNEx

StringCchCopyN

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