Condividi tramite


Funzione PSFormatForDisplayAlloc (propsys.h)

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à