PSFormatForDisplay function (propsys.h)
Gets a formatted, Unicode string representation of a property value stored in a PROPVARIANT structure. The caller is responsible for allocating the output buffer.
Syntax
PSSTDAPI PSFormatForDisplay(
[in] REFPROPERTYKEY propkey,
[in] REFPROPVARIANT propvar,
[in] PROPDESC_FORMAT_FLAGS pdfFlags,
[out] LPWSTR pwszText,
[in] DWORD cchText
);
Parameters
[in] propkey
Type: REFPROPERTYKEY
Reference to a PROPERTYKEY that names the property whose value is being retrieved.
[in] propvar
Type: REFPROPVARIANT
Reference to a PROPVARIANT structure that contains the type and value of the property.
[in] pdfFlags
Type: PROPDESC_FORMAT_FLAGS
A flag that specifies the format to apply to the property string. See PROPDESC_FORMAT_FLAGS for possible values.
[out] pwszText
Type: LPWSTR
When the function returns, contains a pointer to the formatted value as a null-terminated, Unicode string. The calling application is responsible for allocating memory for the buffer before it calls PSFormatForDisplay.
[in] cchText
Type: DWORD
Specifies the length of the buffer at pwszText in WCHARs, including the terminating null character.
Return value
Type: HRESULT
Returns one of the following values.
Return code | Description |
---|---|
|
The formatted string was successfully created. |
|
The formatted string was not created. S_FALSE indicates that an empty string resulted from a VT_EMPTY. |
|
Indicates allocation failed. |
Remarks
This function calls the schema subsystem's implementation of IPropertySystem::FormatForDisplay. That call provides a Unicode string representation of a property value, with additional formatting based on one or more PROPDESC_FORMAT_FLAGS. If the PROPERTYKEY is not recognized by the schema subsystem, IPropertySystem::FormatForDisplay attempts to format the value according to the value's VARTYPE.
You must initialize Component Object Model (COM) with CoInitialize or OleInitialize before you call PSFormatPropertyValue.
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.
Property | Format |
---|---|
System.FileAttributes | The following file attributes are converted to letters and appended to create a string (for example, a value of 0x1801 is converted to "RCO"): |
FILE_ATTRIBUTE_READONLY- 'R' | |
FILE_ATTRIBUTE_SYSTEM - 'S' | |
FILE_ATTRIBUTE_ARCHIVE -'A' | |
FILE_ATTRIBUTE_COMPRESSED - 'C' | |
FILE_ATTRIBUTE_ENCRYPTED - 'E' | |
FILE_ATTRIBUTE_OFFLINE - 'O' | |
FILE_ATTRIBUTE_NOT_CONTENT_INDEXED - 'I' | |
System.Photo.ISOSpeed | For example, "ISO-400". |
System.Photo.ShutterSpeed |
The APEX value is converted to an exposure time using this formula:
For example, "2 sec."or "1/125 sec.". |
System.Photo.ExposureTime | For example, "2 sec."or "1/125 sec." |
System.Photo.Aperture |
The APEX value is converted to an F number using this formula:
For example, "f/5.6". |
System.Photo.FNumber | For example, "f/5.6". |
System.Photo.SubjectDistance | For example, "15 m"or "250 mm". |
System.Photo.FocalLength | For example, "50 mm". |
System.Photo.FlashEnergy | For example, "500 bpcs". |
System.Photo.ExposureBias | For example, "-2 step", " 0 step", or "+3 step". |
System.Computer.DecoratedFreeSpace | For example, "105 MB free of 13.2 GB". |
System.ItemType | For example, "Application" or "JPEG Image". |
System.ControlPanel.Category | For example, "Appearance and Personalization". |
System.ComputerName | For 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 value | Format |
---|---|
VT_BOOLEAN | Not supported. |
VT_FILETIME | Date/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 VARTYPE | Decimal string in the current locale. For example, "42". |
VT_LPWSTR or other | Converted to a string. Sequences of "\r", "\t", or "\n" are replaced with a single space. |
VT_VECTOR | anything | Semicolon 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 PSFormatForDisplay to format a rating value.
PROPVARIANT propvar;
HRESULT hr = InitPropVariantFromUInt32(RATING_THREE_STARS_SET, &propvar);
if (SUCCEEDED(hr))
{
WCHAR szValue[100];
hr = PSFormatForDisplay(PKEY_Rating, propvar, PDFF_DEFAULT, szValue, ARRAYSIZE(szValue));
if (SUCCEEDED(hr))
{
// szValue contains a formatted string similar to "3 stars".
}
PropVariantClear(&propvar);
}
Requirements
Requirement | Value |
---|---|
Minimum supported client | Windows Vista [desktop apps only] |
Minimum supported server | Windows Server 2008 [desktop apps only] |
Target Platform | Windows |
Header | propsys.h |
Library | Propsys.lib |
DLL | Propsys.dll (version 6.0 or later) |
Redistributable | Windows Desktop Search (WDS) 3.0 |