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


Функция PSFormatForDisplayAlloc (propsys.h)

Возвращает форматируемое строковое представление в Юникоде значения свойства, хранящегося в структуре PROPVARIANT . Эта функция выделяет память для выходной строки.

Синтаксис

PSSTDAPI PSFormatForDisplayAlloc(
  [in]  REFPROPERTYKEY        key,
  [in]  REFPROPVARIANT        propvar,
  [in]  PROPDESC_FORMAT_FLAGS pdff,
  [out] PWSTR                 *ppszDisplay
);

Параметры

[in] key

Тип: REFPROPERTYKEY

Ссылка на PROPERTYKEY с именем свойства, значение которого извлекается.

[in] propvar

Тип: REFPROPVARIANT

Ссылка на структуру PROPVARIANT , содержащую тип и значение свойства.

[in] pdff

Тип: PROPDESC_FORMAT_FLAGS

Один или несколько флагов, указывающих формат, применяемый к строке свойства. Возможные значения см. в PROPDESC_FORMAT_FLAGS .

[out] ppszDisplay

Тип: PWSTR*

При возврате функции содержит указатель на строковое представление запрошенного свойства в Юникоде, завершающееся null.

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

Тип: HRESULT

Возвращает одно из следующих значений.

Код возврата Описание
S_OK
Форматированная строка успешно создана. S_OK вместе с пустой возвращаемой строкой означает наличие пустой входной строки или непустого значения, отформатированного как пустая строка.
S_FALSE
Форматированная строка не создана. S_FALSE вместе с пустой возвращаемой строкой указывает, что пустая строка является результатом VT_EMPTY.
E_OUTOFMEMORY
Указывает, что выделение ресурсов завершилось сбоем.

Комментарии

Эта функция вызывает реализацию подсистемы схемы IPropertySystem::FormatForDisplayAlloc. Этот вызов предоставляет строковое представление значения свойства в Юникоде с дополнительным форматированием на основе одного или нескольких PROPDESC_FORMAT_FLAGS. Если propertyKEY не распознается подсистемой схемы, IPropertySystem::FormatForDisplayAlloc пытается отформатировать значение в соответствии с VARTYPE значения.

Перед вызовом PSFormatForDisplayAlloc необходимо инициализировать компонентную объектную модель (COM) с помощью CoInitialize или OleInitialize.

Функция выделяет память с помощью CoTaskMemAlloc и возвращает указатель на нее с помощью параметра ppszDisplay . Вызывающее приложение должно использовать CoTaskMemFree , чтобы освободить этот ресурс, когда он больше не нужен.

Эта функция предназначена для преобразования данных в строку, подходящую для отображения пользователю. Значение форматируется в соответствии с текущим языковым стандартом, языком пользователя, PROPDESC_FORMAT_FLAGS и описанием свойства, указанным ключом свойства. Сведения о том, как схема описания свойства влияет на форматирование значения, см. в следующих разделах:

Как правило, PROPDESC_FORMAT_FLAGS используются для изменения формата, предписанного описанием свойства.

Выходная строка может содержать символы направления Юникода. Эти символы влияют на двунаправленный алгоритм Юникода, чтобы значения отображались правильно при рисовании языка слева направо (LTR) в окне справа налево (RTL) или при рисовании RTL в окне LTR. К этим символам относятся следующие: "\x200e", "\x200f", "\x202a", "\x202b", "\x202c", "\x202d", "\x202e".

Следующие свойства используют специальные форматы и не затрагиваются PROPDESC_FORMAT_FLAGS. Обратите внимание, что приведенные примеры относятся к строкам с текущим языковым стандартом , установленным на английском языке; как правило, выходные данные локализованы, за исключением случаев, когда указано.

Свойство Формат
System.FileAttributes Следующие атрибуты файла преобразуются в буквы и добавляются для создания строки (например, значение 0x1801 (FILE_ATTRIBUTE_READONLY | FILE_ATTRIBUTE_COMPRESSED | FILE_ATTRIBUTE_OFFLINE) преобразуется в RCO):
  • FILE_ATTRIBUTE_READONLY (0x00000001) — R
  • FILE_ATTRIBUTE_SYSTEM (0x00000004) — S
  • FILE_ATTRIBUTE_ARCHIVE (0x00000020) -'A'
  • FILE_ATTRIBUTE_COMPRESSED (0x00000800) — 'C'
  • FILE_ATTRIBUTE_ENCRYPTED (0x00004000) — E
  • FILE_ATTRIBUTE_OFFLINE (0x00001000) — O
  • FILE_ATTRIBUTE_NOT_CONTENT_INDEXED (0x00002000) — I
System.Photo.ISOSpeed Например, ISO-400.
System.Photo.ShutterSpeed Значение APEX преобразуется в время экспозиции с помощью следующей формулы:

Exposure_time = 2^(-APEX_value)

Например, "2 секунды". или "1/125 с".

System.Photo.ExposureTime Например, "2 секунды". или "1/125 с".
System.Photo.Aperture Значение APEX преобразуется в число F с помощью следующей формулы:

F_Number = 2^(APEX_Value / 2)

Например, "f/5.6".

System.Photo.FNumber Например, "f/5.6".
System.Photo.SubjectDistance Например, "15 м" или "250 мм".
System.Photo.FocalLength Например, "50 мм".
System.Photo.Flash Например, "500 бит/с".
System.Photo.ExposureBias Например, "шаг -2", "0 шаг" или "+3 шаг".
System.Computer.DecoratedFreeSpace Например, "105 МБ бесплатно 13,2 ГБ".
System.ItemType Например, "Приложение" или "Изображение JPEG".
System.ControlPanel.Category Например, "Внешний вид и персонализация".
System.ComputerName Например, "LITWARE05 (этот компьютер)" или "testbox07".
 

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

Тип значения Формат
VT_BOOLEAN Не поддерживается.
VT_FILETIME Строка даты и времени в соответствии с PROPDESC_FORMAT_FLAGS и текущим языковым стандартом. PDFF_SHORTTIME и PDFF_SHORTDATE используются по умолчанию. Например, "13.11.2006 15:22".
Numeric VARTYPE Десятичная строка в текущем языковом стандарте. Например, "42".
VT_LPWSTR или другое Преобразуется в строку. Последовательности "\r", "\t" или "\n" заменяются одним пробелом.
VT_VECTOR | Ничего Значения, разделенные точкой с запятой. Точка с запятой используется независимо от языкового стандарта.
 

Примеры

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

PROPVARIANT propvar;

HRESULT hr = InitPropVariantFromUInt32(RATING_THREE_STARS_SET, &propvar);

if (SUCCEEDED(hr))
{
    PWSTR pszValue;

    hr = PSFormatForDisplayAlloc(PKEY_Rating, propvar, PDFF_DEFAULT, &pszValue);

    if (SUCCEEDED(hr))
    {
        // pszValue contains a formatted string similar to "3 stars".
         CoTaskMemFree(pszValue);
    }
    PropVariantClear(&propvar);
}

Требования

Требование Значение
Минимальная версия клиента Windows Vista [только классические приложения]
Минимальная версия сервера Windows Server 2008 [только классические приложения]
Целевая платформа Windows
Header propsys.h
Библиотека Propsys.lib
DLL Propsys.dll (версия 6.0 или более поздняя)
Распространяемые компоненты Windows Desktop Search (WDS) 3.0

См. также раздел

PSFormatForDisplay

PSFormatPropertyValue

Схема описания свойства