Функция StringCchCopyNEx - замена функции strncpy. StringCchCopyNEx копирует заданное число символов из исходной строки. Размер, в символах, целевого буфера назначается в функцию для того, чтобы гарантировать, что StringCchCopyNEx не запишет помимо конца этого буфера. StringCchCopyNEx добавляет к функциональным возможностям StringCchCopyN, возвращение указателя на конец строки, являющейся выходным значением, а так же число символов оставшееся неиспользуемым в этой строке. В функцию для дополнительного управления могут также передаваться флажки.
HRESULT StringCchCopyNEx( LPTSTR pszDest, size_t cchDest, LPCTSTR pszSrc, size_t cchSrc, LPTSTR *ppszDestEnd, size_t *pcchRemaining, DWORD dwFlags ); |
[out] Указатель на буфер, который получает скопированную строку.
cchDest[in] Размер pszDest, в символах. Это значение должно быть по крайней мере достаточно большим, чтобы содержать скопированные символы (длиной pszSrc или значение cchSrc, тот который меньше) плюс 1, чтобы принять во внимание символ завершающего нуля. Максимальное число допустимых символов является STRSAFE_MAX_CCH.
pszSrc[in] Указатель на буфер, содержащий исходную строку. Эта исходная строка должна быть завершена символом конца строки ('\0').
cchSrc[in] Максимальное число символов, чтобы скопировать из pszSrc в pszDest.
ppszDestEnd[out] Адрес указателя на конец pszDest. Если ppszDestEnd не-NULL, а какие-либо данные скопированы в целевой буфер, параметр указывает на символ завершающего нуля в конце строки.
pcchRemaining[out] Указатель на переменную, которая указывает число неиспользуемых символов в pszDest, включая символ завершающего нуля. Если pcchRemaining - 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, pszDest - NULL, когда имеются предоставленные исходные данные для копирования, или передан недопустимый флажок. |
| STRSAFE_E_INSUFFICIENT_BUFFER | Операция копирования завершалась ошибкой из-за недостаточного места в буфере. В зависимости от значения dwFlags целевой буфер может содержать обрезанную, версию с нулевым символом в конце предполагаемого результата. В ситуациях, где усечение является приемлемым, это может не обязательно быть отмечено как условие сбоя. |
Функция StringCchCopyNEx предусматривает дополнительную обработку для правильной работы буфера в Вашем коде. Недостаточная обработка буфера влечет за собой во многие проблемы обеспечения безопасности, которые вызывают переполнение буфера. StringCchCopyNEx всегда завершает символом конца строки ('\0') целевой буфер ненулевой длины.
Функция StringCchCopyNEx может быть использована в своей общей форме, или в специальной типа StringCchCopyNExA (для строк ANSI) или StringCchCopyNExW (для строк Unicode). Форма использования определяется Вашими данными.
Тип строковых данных |
Строковый литерал |
Функция |
|---|---|---|
| char | "string" | StringCchCopyNExA |
| TCHAR | TEXT("string") | StringCchCopyNEx |
| WCHAR | L"string" | StringCchCopyNExW |
Наряду с тем, что эта процедура предназначается как замена для strncpy, есть различия в их поведении. Если cchSrc больше, чем число символов в pszSrc, StringCchCopyN, в отличие от strncpy, не продолжает дополнять pszDest нулевыми символами до тех пор, пока символы cchSrc не скопируются.
Поведение становится неопределенным, если строки указанные при помощи параметров pszSrc и pszDest - перекрываются.
Ни pszSrc, ни pszDest не должны быть NULL, если не определяется флажок STRSAFE_IGNORE_NULLS, при котором в этом случае, оба могут быть NULL. Однако, ошибка из-за недостаточного места может все еще возвратиться даже при том, что игнорируются нулевые значения.
Обзор Строки, Функции, используемые строками, StringCbCopyNEx, StringCchCopyN
Размещение и совместимость StringCchCopyNEx |
||
| К | 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. | |
| Замечания по платформе | Не имеется | |
