Funzione PSFormatForDisplayAlloc (propsys.h)

Articolo
03/01/2024

Ottiene una rappresentazione di stringa Unicode formattata di un valore di proprietà archiviato in una struttura PROPVARIANT . Questa funzione alloca memoria per la stringa di output.

Sintassi

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

Parametri

[in] key

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] pdff

Tipo: PROPDESC_FORMAT_FLAGS

Uno o più flag che specificano il formato da applicare alla stringa di proprietà. Per i valori possibili, vedere PROPDESC_FORMAT_FLAGS.

[out] ppszDisplay

Tipo: PWSTR*

Quando la funzione viene restituita, contiene un puntatore a una rappresentazione di stringa Unicode con terminazione Null del valore della proprietà richiesta.

Valore restituito

Tipo: HRESULT

Restituisce uno dei valori seguenti.

Codice restituito	Descrizione
S_OK	La stringa formattata è stata creata correttamente. S_OK insieme a una stringa restituita vuota indica che è presente una stringa di input vuota o un valore non vuoto formattato come stringa vuota.
S_FALSE	La stringa formattata non è stata creata. S_FALSE insieme a una stringa restituita vuota indica che la 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::FormatForDisplayAlloc. 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::FormatForDisplayAlloc 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 PSFormatForDisplayAlloc.

La funzione alloca la memoria tramite CoTaskMemAlloc e restituisce un puntatore a tale memoria tramite il parametro ppszDisplay . L'applicazione chiamante deve usare CoTaskMemFree per rilasciare tale risorsa quando non è più necessaria.

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 (FILE_ATTRIBUTE_READONLY \| FILE_ATTRIBUTE_COMPRESSED \| FILE_ATTRIBUTE_OFFLINE) viene convertito in "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	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 PSFormatForDisplayAlloc per formattare un valore di classificazione.

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

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

PSFormatForDisplay

PSFormatPropertyValue

Schema Descrizione proprietà

Condividi tramite