Функция StringCchVPrintfEx

Функция StringCchVPrintfEx - заменяет функцию vsprintf. Она принимает форматирующую строку и ее параметры, предусмотренные как va_list и возвращает отформатированную строку. Размер, в символах, целевого буфера назначается в функцию, чтобы гарантировать, что StringCchVPrintfEx не запишет помимо конца этого буфера. StringCchVPrintfEx добавляет к функциональным возможностям функции StringCchVPrintf возвращение указателя на конец строки, являющейся выходным значением, а так же число символов, оставшееся неиспользуемым в этой строке. Для дополнительного управления в функцию могут также передаваться флажки.

Синтаксис

HRESULT StringCchVPrintfEx(      

    LPTSTR pszDest,
    size_t cchDest,
    LPTSTR *ppszDestEnd,
    size_t *pcchRemaining,
    DWORD dwFlags,
    LPCTSTR pszFormat,
    va_list argList
);

Параметры

pszDest

[out] Указатель на буфер, который получает отформатированную строку с завершающим нулем, созданную из pszFormat и argList.

cchDest

[in] Размер целевого буфера, в символах. Это значение должно быть достаточно большим, чтобы вместить конечную отформатированную строку плюс 1, чтобы принять во внимание символ завершающего нуля. Максимальное число допустимых символов является STRSAFE_MAX_CCH.

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, любая обрезанная строка перезаписывается.
  • pszFormat

    [in] Указатель на буфер, содержащий форматирующую строку printf-стиля. Эта строка должна быть завершена символом конца строки ('\0').

    argList

    [in] va_list, содержащий параметры, которые будут вставлены в pszFormat.

    Возвращаемое значение

    Обратите внимание! на то, что возвращаемое значение функцией - HRESULT, в противоположность функции vsprintf, которая возвращает число записанных символов. Поэтому настоятельно рекомендуется использовать макроопределения SUCCEEDED и FAILED, чтобы проверить возвращаемое значение этой функцией.


    Возвращаемое значение

    Описание

    S_OK Было достаточное место для результата копирования в pszDest без усечения и буфер завершен символом конца строки ('\0').
    STRSAFE_E_INVALID_PARAMETER Значение в cchDest или 0, или больше, чем STRSAFE_MAX_CCH, или целевой буфер уже заполнен.
    STRSAFE_E_INSUFFICIENT_BUFFER Операция копирования завершалась ошибкой из-за недостаточного пространства буфера. В зависимости от значения dwFlags целевой буфер может содержать обрезанную версию с нулевым символом в конце предполагаемого результата ( строки). В ситуациях, где усечение является приемлемым, это может не обязательно быть замечено как условие сбоя.

    Замечания

    Функция StringCchVPrintfEx предусматривает дополнительную обработку для правильной работы буфера в Вашем коде. Недостаточная обработка буфера влечет за собой многие проблемы обеспечения безопасности, которые вызывают переполнение буфера. StringCchVPrintfEx всегда завершает символом конца строки ('\0') целевой буфер ненулевой длины.

    Дополнительную информацию о va_lists, см.в статье о соглашениях, определенных в заголовочном файле Stdarg.h.

    Функция StringCchVPrintfEx может быть использована в своей общей форме, или в специальной, такой как StringCchVPrintfExA (для строк ANSI) или StringCchVPrintfExW (для строк Unicode. Форма использования определяется Вашими данными.

    Тип строковых данных

    Строковый литерал

    Функция

    char "string" StringCchVPrintfExA
    TCHAR TEXT("string") StringCchVPrintfEx
    WCHAR L"string" StringCchVPrintfExW

    StringCchVPrintfEx и её ANSI и Unicode варианты - заменяют эти функции:

    Поведение не определяется, если строки указанные при помощи pszDest, pszFormat, или какие-либо параметры строк перекрываются.

    Ни pszFormat, ни pszDest не должны быть NULL, если не определяется флажок STRSAFE_IGNORE_NULLS, при котором, в этом случае, оба параметра могут быть NULL. Однако, ошибка из-за недостаточного места может все еще возвратиться даже при том, что игнорируются нулевые значения.

    Смотри также

    Обзор Строки, Функции, используемые строкамиStringCbVPrintfEx, StringCchVPrintf, StringCchPrintfEx

    Размещение и совместимость StringCchVPrintfEx

    К 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.
    Замечания по платформе Не имеется

     

    Назад в оглавление
    На главную страницу
    В оглавление справки

    Hosted by uCoz