PSFormatForDisplayAlloc-Funktion (propsys.h)

Artikel
08/25/2023

Ruft eine formatierte Unicode-Zeichenfolgendarstellung eines Eigenschaftswerts ab, der in einer PROPVARIANT-Struktur gespeichert ist. Diese Funktion weist Arbeitsspeicher für die Ausgabezeichenfolge zu.

Syntax

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

Parameter

[in] key

Typ: REFPROPERTYKEY

Verweis auf einen PROPERTYKEY , der die Eigenschaft benennt, deren Wert abgerufen wird.

[in] propvar

Typ: REFPROPVARIANT

Verweis auf eine PROPVARIANT-Struktur , die den Typ und den Wert der Eigenschaft enthält.

[in] pdff

Typ: PROPDESC_FORMAT_FLAGS

Mindestens ein Flag, das das Format angibt, das auf die Eigenschaftenzeichenfolge angewendet werden soll. Mögliche Werte finden Sie unter PROPDESC_FORMAT_FLAGS .

[out] ppszDisplay

Typ: PWSTR*

Wenn die Funktion zurückgibt, enthält einen Zeiger auf eine mit NULL beendete Unicode-Zeichenfolgendarstellung des angeforderten Eigenschaftswerts.

Rückgabewert

Typ: HRESULT

Gibt einen der folgenden Werte zurück.

Rückgabecode	BESCHREIBUNG
S_OK	Die formatierte Zeichenfolge wurde erfolgreich erstellt. S_OK zusammen mit einer leeren Rückgabezeichenfolge gibt an, dass es eine leere Eingabezeichenfolge oder einen nicht leeren Wert gab, der als leere Zeichenfolge formatiert wurde.
S_FALSE	Die formatierte Zeichenfolge wurde nicht erstellt. S_FALSE zusammen mit einer leeren Rückgabezeichenfolge gibt an, dass die leere Zeichenfolge aus einer VT_EMPTY resultiert.
E_OUTOFMEMORY	Gibt an, dass bei der Zuordnung ein Fehler aufgetreten ist.

Hinweise

Diese Funktion ruft die Implementierung von IPropertySystem::FormatForDisplayAlloc im Schemasubsystem auf. Dieser Aufruf bietet eine Unicode-Zeichenfolgendarstellung eines Eigenschaftswerts mit zusätzlicher Formatierung basierend auf einem oder mehreren PROPDESC_FORMAT_FLAGS. Wenn PROPERTYKEY vom Schemasubsystem nicht erkannt wird, versucht IPropertySystem::FormatForDisplayAlloc , den Wert entsprechend dem VARTYPE des Werts zu formatieren.

Sie müssen das Component Object Model (COM) mit CoInitialize oder OleInitialize initialisieren , bevor Sie PSFormatForDisplayAlloc aufrufen.

Die Funktion weist Arbeitsspeicher über CoTaskMemAlloc zu und gibt einen Zeiger auf diesen Speicher über den ppszDisplay-Parameter zurück. Die aufrufende Anwendung muss CoTaskMemFree verwenden, um diese Ressource freizugeben, wenn sie nicht mehr benötigt wird.

Der Zweck dieser Funktion besteht darin, Daten in eine Zeichenfolge zu konvertieren, die für die Anzeige für den Benutzer geeignet ist. Der Wert wird entsprechend dem aktuellen Gebietsschema, der Sprache des Benutzers, dem PROPDESC_FORMAT_FLAGS und der Durch den Eigenschaftenschlüssel angegebenen Eigenschaftenbeschreibung formatiert. Informationen dazu, wie das Eigenschaftenbeschreibungsschema die Formatierung des Werts beeinflusst, finden Sie in den folgenden Themen:

In der Regel werden die PROPDESC_FORMAT_FLAGS verwendet, um das in der Eigenschaftenbeschreibung vorgeschriebene Format zu ändern.

Die Ausgabezeichenfolge kann Unicode-Richtungszeichen enthalten. Diese nicht überziehenden Zeichen beeinflussen den bidirektionalen Unicode-Algorithmus, sodass die Werte richtig angezeigt werden, wenn eine LTR-Sprache (Left-to-Right) in einem RTL-Fenster (Right-to-Left) gezeichnet wird oder ein RTL in einem LTR-Fenster gezeichnet wird. Diese Zeichen umfassen Folgendes: "\x200e", "\x200f", "\x202a", "\x202b", "\x202c", "\x202d", "\x202e".

Die folgenden Eigenschaften verwenden spezielle Formate und sind vom PROPDESC_FORMAT_FLAGS nicht betroffen. Beachten Sie, dass die angegebenen Beispiele für Zeichenfolgen gelten, deren aktuelles Gebietsschema auf Englisch festgelegt ist. In der Regel wird die Ausgabe lokalisiert, sofern nicht angegeben.

Eigenschaft	Format
System.FileAttributes	Die folgenden Dateiattribute werden in Buchstaben konvertiert und angefügt, um eine Zeichenfolge zu erstellen (z. B. ein Wert von 0x1801 (FILE_ATTRIBUTE_READONLY \| FILE_ATTRIBUTE_COMPRESSED \| FILE_ATTRIBUTE_OFFLINE) wird in "RCO" konvertiert): 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	Beispiel: "ISO-400".
System.Photo.ShutterSpeed	Der APEX-Wert wird mithilfe dieser Formel in eine Belichtungszeit konvertiert: `Exposure_time = 2^(-APEX_value)` Beispiel: "2 Sekunden". oder "1/125 Sek.".
System.Photo.ExposureTime	Beispiel: "2 Sekunden". oder "1/125 Sekunden".
System.Photo.Aperture	Der APEX-Wert wird mithilfe dieser Formel in eine F-Zahl konvertiert: `F_Number = 2^(APEX_Value / 2)` Beispiel: "f/5.6".
System.Photo.FNumber	Beispiel: "f/5.6".
System.Photo.SubjectDistance	Beispiel: "15 m" oder "250 mm".
System.Photo.FocalLength	Beispiel: "50 mm".
System.Photo.FlashEnergy	Beispiel: "500 bpcs".
System.Photo.ExposureBias	Beispiel: "-2 Schritt", "0 Schritt" oder "+3 Schritt".
System.Computer.DecoratedFreeSpace	Beispiel: "105 MB frei von 13,2 GB".
System.ItemType	Beispiel: "Anwendung" oder "JPEG-Bild".
System.ControlPanel.Category	Beispiel: "Darstellung und Personalisierung".
System.ComputerName	Beispiel: "LITWARE05 (dieser Computer)" oder "testbox07".

Wenn der Eigenschaftenschlüssel keiner Eigenschaftsbeschreibung in einem der registrierten Eigenschaftenschemas entspricht, wählt diese Funktion ein Format basierend auf dem Typ des Werts aus.

Typ des Werts	Format
VT_BOOLEAN	Wird nicht unterstützt.
VT_FILETIME	Datums-/Uhrzeitzeichenfolge, wie durch PROPDESC_FORMAT_FLAGS und das aktuelle Gebietsschema angegeben. PDFF_SHORTTIME und PDFF_SHORTDATE sind die Standardeinstellung. Beispiel: "13.11.2006 15:22 Uhr".
Numerischer VARTYPE	Dezimalzeichenfolge im aktuellen Gebietsschema. Beispiel: "42".
VT_LPWSTR oder andere	In eine Zeichenfolge konvertiert. Sequenzen von "\r", "\t" oder "\n" werden durch ein einzelnes Leerzeichen ersetzt.
VT_VECTOR \| Etwas	Durch Semikolon getrennte Werte. Ein Semikolon wird unabhängig vom Gebietsschema verwendet.

Beispiele

Im folgenden Beispiel, das als Teil eines größeren Programms eingeschlossen werden soll, wird veranschaulicht, wie Sie PSFormatForDisplayAlloc verwenden, um einen Bewertungswert zu formatieren.

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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	propsys.h
Bibliothek	Propsys.lib
DLL	Propsys.dll (Version 6.0 oder höher)
Verteilbare Komponente	Windows Desktop Search (WDS) 3.0

Weitere Informationen

PSFormatForDisplay

PSFormatPropertyValue

Eigenschaftenbeschreibungsschema

Freigeben über