Funzione PSFormatForDisplay (propsys.h)

Articolo
03/01/2024

Ottiene una rappresentazione di stringa Unicode formattata di un valore di proprietà archiviato in una struttura PROPVARIANT . Il chiamante è responsabile dell'allocazione del buffer di output.

Sintassi

PSSTDAPI PSFormatForDisplay(
  [in]  REFPROPERTYKEY        propkey,
  [in]  REFPROPVARIANT        propvar,
  [in]  PROPDESC_FORMAT_FLAGS pdfFlags,
  [out] LPWSTR                pwszText,
  [in]  DWORD                 cchText
);

Parametri

[in] propkey

Tipo: REFPROPERTYKEY

Riferimento a un valore PROPERTYKEY che assegna un nome alla proprietà il cui valore viene recuperato.

[in] propvar

Tipo: REFPROPVARIANT

Riferimento a una struttura PROPVARIANT che contiene il tipo e il valore della proprietà.

[in] pdfFlags

Tipo: PROPDESC_FORMAT_FLAGS

Flag che specifica il formato da applicare alla stringa di proprietà. Per i valori possibili, vedere PROPDESC_FORMAT_FLAGS.

[out] pwszText

Tipo: LPWSTR

Quando la funzione viene restituita, contiene un puntatore al valore formattato come stringa Unicode con terminazione Null. L'applicazione chiamante è responsabile dell'allocazione della memoria per il buffer prima di chiamare PSFormatForDisplay.

[in] cchText

Tipo: DWORD

Specifica la lunghezza del buffer in pwszText in WCHAR, incluso il carattere Null di terminazione.

Valore restituito

Tipo: HRESULT

Restituisce uno dei valori seguenti.

Codice restituito	Descrizione
S_OK	La stringa formattata è stata creata correttamente.
S_FALSE	La stringa formattata non è stata creata. S_FALSE indica che una stringa vuota è stata generata da un VT_EMPTY.
E_OUTOFMEMORY	Indica che l'allocazione non è riuscita.

Commenti

Questa funzione chiama l'implementazione del sottosistema dello schema di IPropertySystem::FormatForDisplay. Tale chiamata fornisce una rappresentazione di stringa Unicode di un valore di proprietà, con formattazione aggiuntiva basata su una o più PROPDESC_FORMAT_FLAGS. Se PROPERTYKEY non viene riconosciuto dal sottosistema dello schema, IPropertySystem::FormatForDisplay tenta di formattare il valore in base al valore VARTYPE del valore.

È necessario inizializzare Component Object Model (COM) con CoInitialize o OleInitialize prima di chiamare PSFormatPropertyValue.

Lo scopo di questa funzione è convertire i dati in una stringa adatta per la visualizzazione all'utente. Il valore viene formattato in base alle impostazioni locali correnti, alla lingua dell'utente, al PROPDESC_FORMAT_FLAGS e alla descrizione della proprietà specificata dalla chiave della proprietà. Per informazioni su come lo schema della descrizione della proprietà influisce sulla formattazione del valore, vedere gli argomenti seguenti:

In genere, il PROPDESC_FORMAT_FLAGS viene usato per modificare il formato prescritto dalla descrizione della proprietà.

La stringa di output può contenere caratteri direzionali Unicode. Questi caratteri nonpacing influenzano l'algoritmo bidirezionale Unicode in modo che i valori vengano visualizzati correttamente quando viene disegnato un linguaggio LTR (Left-to-Right) in una finestra RTL (Right-to-Left) o un RTL viene disegnato in una finestra LTR. Questi caratteri includono i seguenti: "\x200e", "\x200f", "\x202a", "\x202b", "\x202c", "\x202d", "\x202e".

Le proprietà seguenti usano formati speciali e non sono interessate dalla PROPDESC_FORMAT_FLAGS. Si noti che gli esempi citati sono per le stringhe con impostazioni locali correnti impostate su Inglese; in genere, l'output viene localizzato tranne dove indicato.

Proprietà	Format
System.FileAttributes	Gli attributi di file seguenti vengono convertiti in lettere e aggiunti per creare una stringa (ad esempio, un valore di 0x1801 viene convertito in "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	Ad esempio, "ISO-400".
System.Photo.ShutterSpeed	Il valore APEX viene convertito in un tempo di esposizione usando questa formula: `Exposure_time = 2^(-APEX_value)` Ad esempio, "2 sec". o "1/125 sec.".
System.Photo.ExposureTime	Ad esempio, "2 sec". o "1/125 sec".
System.Photo.Aperture	Il valore APEX viene convertito in un numero F usando questa formula: `F_Number = 2^(APEX_Value / 2)` Ad esempio, "f/5.6".
System.Photo.FNumber	Ad esempio, "f/5.6".
System.Photo.SubjectDistance	Ad esempio, "15 m"o "250 mm".
System.Photo.FocalLength	Ad esempio, "50 mm".
System.Photo.Flash Dottorato	Ad esempio, "500 bpcs".
System.Photo.ExposureBias	Ad esempio, "-2 step", " 0 step" o "+3 step".
System.Computer.DecoratedFreeSpace	Ad esempio, "105 MB gratuito di 13,2 GB".
System.ItemType	Ad esempio, "Application" o "JPEG Image".
System.ControlPanel.Category	Ad esempio, "Aspetto e personalizzazione".
System.ComputerName	Ad esempio, "LITWARE05 (questo computer)" o "testbox07".

Se la chiave della proprietà non corrisponde a una descrizione di proprietà in uno degli schemi di proprietà registrati, questa funzione sceglie un formato in base al tipo del valore.

Tipo del valore	Formato
VT_BOOLEAN	Non supportato.
VT_FILETIME	Stringa di data/ora come specificato da PROPDESC_FORMAT_FLAGS e dalle impostazioni locali correnti. PDFF_SHORTTIME e PDFF_SHORTDATE sono l'impostazione predefinita. Ad esempio, "13/11/2006 13:22".
VARTYPE numerico	Stringa decimale nelle impostazioni locali correnti. Ad esempio, "42".
VT_LPWSTR o altro	Convertito in una stringa. Le sequenze di "\r", "\t" o "\n" vengono sostituite con un singolo spazio.
VT_VECTOR \| Nulla	Valori separati da punto e virgola. Viene usato un punto e virgola indipendentemente dalle impostazioni locali.

Esempio

Nell'esempio seguente, da includere come parte di un programma più ampio, viene illustrato come usare PSFormatForDisplay per formattare un valore di classificazione.

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

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	propsys.h
Libreria	Propsys.lib
DLL	Propsys.dll (versione 6.0 o successiva)
Componente ridistribuibile	Windows Desktop Search (WDS) 3.0

Vedi anche

PSFormatForDisplayAlloc

PSFormatPropertyValue

Schema Descrizione proprietà

Condividi tramite