Функция StringCbCopyNEx - это замена для функции strncpy. StringCbCopyNEx копирует заданное число байтов из исходной строки. Размер, в байтах, целевого буфера передается в функцию, чтобы гарантировать, что StringCbCopyNEx не запишет помимо конца этого буфера. StringCbCopyNEx добавляет к функциональным возможностям функции StringCbCopyN возвращение указателя на конец строки, являющейся выходным значением, а так же и число байтов оставшееся неиспользованным в этой строке. Для дополнительного управления в функцию могут также передаваться флажки.
HRESULT StringCbCopyNEx( LPTSTR pszDest, size_t cbDest, LPCTSTR pszSrc, size_t cbSrc, LPTSTR *ppszDestEnd, size_t *pcbRemaining, DWORD dwFlags ); |
[out] Указатель на буфер, который получает скопированную строку.
cbDest[in] Размер pszDest, в байтах. Это значение должно быть, по крайней мере, достаточно большим, чтобы вместить скопированные байты (фактически не меньше длины pszSrc или значения cbSrc, ), а так же должен быть принят во внимание символ завершающего нуля. Максимальное допустимое число байтов является STRSAFE_MAX_CCH * sizeof (TCHAR).
pszSrc[in] Указатель на буфер, содержащий в себе исходную строку. Эта исходная строка должна быть завершена символом конца строки ('\0').
cbSrc[in] Максимальное число байтов, которое копируется из pszSrc в pszDest.
ppszDestEnd[out] Адрес указателя на конец pszDest. Если ppszDestEnd не-NULL, и любые данные копируются в целевой буфер, то он указывает на символ завершающего нуля в конце строки.
pcbRemaining[out] Указатель на переменную, которая указывает число неиспользованных байтов в pszDest, включая и те, которые используется для символа завершающего нуля. Если pcbRemaining - NULL, подсчет не сохраняется или возвращается значение.
dwFlags[in] Одно или несколько из нижеследующих значений.
Значение |
Предназначение |
| STRSAFE_FILL_BEHIND_NULL | Если функция завершается успешно, младший байт параметра dwFlags (0) используется, чтобы заполнить неинициализированную часть pszDest после символа завершающего нуля. |
| STRSAFE_IGNORE_NULLS | Обрабатывает указатели пустой строки подобно пустым строкам ( TEXT ("")). |
| STRSAFE_FILL_ON_FAILURE | Если функция завершается ошибкой, младший байт dwFlags (0) используется, чтобы заполнить весь буфер pszDest и буфер завершается символом конца строки ('\0'). В случае сбоя типа STRSAFE_E_INSUFFICIENT_BUFFER, поверх ранее существовавшей, записывается любая обрезанная строка. |
| STRSAFE_NULL_ON_FAILURE | Если функция завершается ошибкой, параметр pszDest устанавливается в пустую строку ( TEXT ("")). В случае сбоя STRSAFE_E_INSUFFICIENT_BUFFER, записывается поверх любая ранее существовавшая или обрезанная строка. |
| STRSAFE_NO_TRUNCATION | Как и в случае STRSAFE_NULL_ON_FAILURE, если функция завершается ошибкой, pszDest устанавливается в пустую строку ( TEXT ("")). В случае сбоя типа STRSAFE_E_INSUFFICIENT_BUFFER поверх записывается любая обрезанная строка. |
 Обратите внимание! на то, что функция возвращает значение
HRESULT в противоположность функции strncpy, которая возвращает указатель. Поэтому настоятельно рекомендуется, что вы использовали макросы
SUCCEEDED и FAILED для проверки возвращаемого значения этой функцией. |
Возвращаемое значение |
Описание |
| S_OK | Исходные данные присутствовали, строки были скопированы без усечения, а итоговый результат целевого буфера завершается символом конца строки ('\0'). |
| STRSAFE_E_INVALID_PARAMETER | Или pszDest, или pszSrc больше, чем STRSAFE_MAX_CCH * sizeof (TCHAR), pszDest - NULL, когда есть исходные данные, представленные для копирования, или передан недопустимый флажок. |
| STRSAFE_E_INSUFFICIENT_BUFFER | Операция копирования завершилась ошибкой из-за недостаточного размера буфера. В зависимости от значения dwFlags целевой буфер может содержать обрезанную, версию с нулевым символом в конце предполагаемого результата. В ситуациях, где усечение является приемлемым, это не обязательно может быть расценено как условие сбоя. |
Функция StringCbCopyNEx предусматривает дополнительную обработку для правильной обработки буфера в вашем коде. Плохая обработка буфера влечет за собой многие проблемы обеспечения безопасности, которые вызывают переполнение буфера. StringCbCopyNEx всегда завершает символом конца строки ('\0') целевой буфер ненулевой длины.
Функция StringCbCopyEx может быть использована в своей унифицированной форме, или специально как StringCbCopyNExA (для строк ANSI) или StringCbCopyExNW (для строк Unicode). Форма использования определяется вашими данными.
Тип данных строки |
Литерал строки |
Функция |
|---|---|---|
| char | "string" | StringCbCopyNExA |
| TCHAR | TEXT("string") | StringCbCopyNEx |
| WCHAR | L"string" | StringCbCopyNExW |
Не смотря на то, что эта стандартная подпрограмма предполагается как замена функции strncpy, все таки имеются различия в их поведении. Если параметр cbSrc больше, чем число байтов в параметре pszSrc, StringCbCopyNEx—в отличие strncpy—не продолжает дополнять pszDest с нулевыми символами до тех пор, пока не будут скопированы байты cbSrc.
Поведение не определяется, если строки указанные при помощи pszSrc и pszDest - частично совпадают.
Ни pszSrc, ни pszDest не должны быть NULL, если не определяется флажок STRSAFE_IGNORE_NULLS , при котором в этом случае, оба могут быть NULL. Однако, ошибка из-за недостаточного пространства может все еще возвратиться даже при том, что игнорируются нулевые (пустые) значения.
Обзор Строки, Функции, используемые строками, StringCbCopyN, StringCchCopyNEx
Размещение и совместимость StringCbCopyNEx |
||
| К | Windows XP | Да |
| л | Windows 2000 Professional | Да |
| и | Windows NT Workstation | Да версии 3.1 |
| е | Windows Me | Да |
| н | Windows 98 | Да |
| т | Windows 95 | Да |
| С | Windows Server 2003 | Да |
| е | Windows 2000 Server | Да |
| р | Windows NT Server | Да версии 3.1 |
| в | ||
| е | ||
| р | ||
| Используемая библиотека | strsafe.lib | |
| Используемая DLL | - | |
| Заголовочный файл | ||
| - объявлено в | strsafe.h | |
| - включено в | - | |
| Unicode | Реализуются как версии Unicode и ANSI. | |
| Замечания по платформе | Не имеется | |
