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

Статья
03/05/2024

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

Синтаксис

PSSTDAPI PSFormatPropertyValue(
  [in]  IPropertyStore        *pps,
  [in]  IPropertyDescription  *ppd,
  [in]  PROPDESC_FORMAT_FLAGS pdff,
  [out] LPWSTR                *ppszDisplay
);

Параметры

[in] pps

Тип: IPropertyStore*

Указатель на IPropertyStore, представляющий хранилище свойств, из которого берется значение свойства.

[in] ppd

Тип: IPropertyDescription*

Указатель на IPropertyDescription, представляющий свойство, значение которого извлекается.

[in] pdff

Тип: PROPDESC_FORMAT_FLAGS

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

[out] ppszDisplay

Тип: LPWSTR*

При возврате функции содержит указатель на форматированное значение в виде строки Юникода, завершаемой null.

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

Тип: HRESULT

Если эта функция завершается успешно, она возвращает S_OK. В противном случае возвращается код ошибки HRESULT .

Эта функция использует параметр ppd для вызова IPropertyDescription::FormatForDisplay. Этот вызов предоставляет строковое представление значения свойства в Юникоде с дополнительным форматированием на основе одного или нескольких PROPDESC_FORMAT_FLAGS.

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

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

Эта функция предназначена для преобразования данных в строку, подходящую для отображения пользователю. Значение форматируется в соответствии с текущим языковым стандартом, языком пользователя, 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 \| Ничего	Значения, разделенные точкой с запятой. Точка с запятой используется независимо от языкового стандарта.

Примеры

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

// IPropertyStore *pStore;
// Assume the variable pps is initialized and valid.
IPropertyDescription *pPropDesc;

HRESULT hr = PSGetPropertyDescription(PKEY_Rating, IID_PPV_ARGS(&pPropDesc));

if (SUCCEEDED(hr))
{
    PWSTR pszValue;

    hr = PSFormatPropertyValue(pStore, pPropDesc, PDFF_DEFAULT, &pszValue);

    if (SUCCEEDED(hr))
    {
        // pszValue contains a formatted string similar to "3 stars".
        CoTaskMemFree(pszValue);
    }
    pPropDesc->Release();
}

Требования

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

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

PSFormatForDisplay

PSFormatForDisplayAlloc

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

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