PSFormatPropertyValue function

Gets a formatted, Unicode string representation of a property value stored in a property store. This function allocates memory for the output string.

Syntax


HRESULT PSFormatPropertyValue(
  _In_   IPropertyStore *pps,
  _In_   IPropertyDescription *ppd,
  _In_   PROPDESC_FORMAT_FLAGS pdff,
  _Out_  LPWSTR *ppszDisplay
);

Parameters

pps [in]

Type: IPropertyStore*

Pointer to an IPropertyStore, which represents the property store from which the property value is taken.

ppd [in]

Type: IPropertyDescription*

Pointer to an IPropertyDescription, which represents the property whose value is being retrieved.

pdff [in]

Type: PROPDESC_FORMAT_FLAGS

One or more PROPDESC_FORMAT_FLAGS that specify the format to apply to the property string. See PROPDESC_FORMAT_FLAGS for possible values.

ppszDisplay [out]

Type: LPWSTR*

When the function returns, contains a pointer to the formatted value as a null-terminated, Unicode string.

Return value

Type: HRESULT

If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

This function uses the ppd parameter to call IPropertyDescription::FormatForDisplay. That call provides a Unicode string representation of a property value, with additional formatting based on one or more PROPDESC_FORMAT_FLAGS.

You must initialize Component Object Model (COM) with CoInitialize or OleInitialize before you call PSFormatPropertyValue.

The function allocates memory and returns a pointer to that memory in ppszDisplay. The calling application must use CoTaskMemFree to release the string specified by ppszDisplay when it is no longer needed.

The purpose of this function is to convert data into a string suitable for display to the user. The value is formatted according to the current locale, the language of the user, the PROPDESC_FORMAT_FLAGS, and the property description specified by the property key. For information on how the property description schema influences the formatting of the value, see the following topics:

Typically, the PROPDESC_FORMAT_FLAGS are used to modify the format prescribed by the property description.

The output string can contain Unicode directional characters. These nonspacing characters influence the Unicode bidirectional algorithm so that the values appear correctly when a left-to-right (LTR) language is drawn on a right-to-left (RTL) window, or an RTL is drawn on a LTR window. These characters include the following: "\x200e", "\x200f", "\x202a", "\x202b", "\x202c", "\x202d", "\x202e".

The following properties use special formats and are unaffected by the PROPDESC_FORMAT_FLAGS. Note that examples cited are for strings with a current locale set to English; typically, output is localized except where noted.

PropertyFormat
System.FileAttributesThe following file attributes are converted to letters and appended to create a string (for example, a value of 0x1801 (FILE_ATTRIBUTE_READONLY | FILE_ATTRIBUTE_COMPRESSED | FILE_ATTRIBUTE_OFFLINE) is converted to "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.ISOSpeedFor example, "ISO-400".
System.Photo.ShutterSpeed

The APEX value is converted to an exposure time using this formula:

Exposure_time = 2^(-APEX_value)

For example, "2 sec."or "1/125 sec.".

System.Photo.ExposureTimeFor example, "2 sec."or "1/125 sec."
System.Photo.Aperture

The APEX value is converted to an F number using this formula:

F_Number = 2^(APEX_Value / 2)

For example, "f/5.6".

System.Photo.FNumberFor example, "f/5.6".
System.Photo.SubjectDistanceFor example, "15 m"or "250 mm".
System.Photo.FocalLengthFor example, "50 mm".
System.Photo.FlashEnergyFor example, "500 bpcs".
System.Photo.ExposureBiasFor example, "-2 step", " 0 step", or "+3 step".
System.Computer.DecoratedFreeSpaceFor example, "105 MB free of 13.2 GB".
System.ItemTypeFor example, "Application" or "JPEG Image".
System.ControlPanel.CategoryFor example, "Appearance and Personalization".
System.ComputerNameFor example, "LITWARE05 (this computer)" or "testbox07".

 

If the property key does not correspond to a property description in any of the registered property schemas, then this function chooses a format based on the type of the value.

Type of the valueFormat
VT_BOOLEANNot supported.
VT_FILETIMEDate/time string as specified by PROPDESC_FORMAT_FLAGS and the current locale. PDFF_SHORTTIME and PDFF_SHORTDATE are the default. For example, "11/13/2006 3:22 PM".
Numeric VARTYPEDecimal string in the current locale. For example, "42".
VT_LPWSTR or otherConverted to a string. Sequences of "\r", "\t", or "\n" are replaced with a single space.
VT_VECTOR | anythingSemicolon separated values. A semicolon is used regardless of locale.

 

Examples

The following example, to be included as part of a larger program, demonstrates how to use PSFormatPropertyValue to format a rating value.


// 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();
}

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Redistributable

Windows Desktop Search (WDS) 3.0

Header

Propsys.h

Library

Propsys.lib

DLL

Propsys.dll (version 6.0 or later)

See also

PSFormatForDisplay
PSFormatForDisplayAlloc
Property Description Schema

 

 

Community Additions

ADD
Show:
© 2014 Microsoft