Funzione PSFormatPropertyValue (propsys.h)

Articolo
03/01/2024

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

Sintassi

PSSTDAPI PSFormatPropertyValue(
  [in]  IPropertyStore        *pps,
  [in]  IPropertyDescription  *ppd,
  [in]  PROPDESC_FORMAT_FLAGS pdff,
  [out] LPWSTR                *ppszDisplay
);

Parametri

[in] pps

Tipo: IPropertyStore*

Puntatore a un archivio IPropertyStore, che rappresenta l'archivio delle proprietà da cui viene preso il valore della proprietà.

[in] ppd

Tipo: IPropertyDescription*

Puntatore a un oggetto IPropertyDescription, che rappresenta la proprietà il cui valore viene recuperato.

[in] pdff

Tipo: PROPDESC_FORMAT_FLAGS

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

[out] ppszDisplay

Tipo: LPWSTR*

Quando la funzione restituisce, contiene un puntatore al valore formattato come stringa Null-terminate, Unicode.

Valore restituito

Tipo: HRESULT

Se questa funzione ha esito positivo, restituisce S_OK. In caso contrario, restituisce un codice di errore HRESULT .

Commenti

Questa funzione usa il parametro ppd per chiamare IPropertyDescription::FormatForDisplay. Tale chiamata fornisce una rappresentazione di stringa Unicode di un valore della proprietà, con formattazione aggiuntiva in base a una o più PROPDESC_FORMAT_FLAGS.

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

La funzione alloca la memoria e restituisce un puntatore alla memoria in ppszDisplay. L'applicazione chiamante deve usare CoTaskMemFree per rilasciare la stringa specificata da ppszDisplay 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, alla PROPDESC_FORMAT_FLAGS e alla descrizione della proprietà specificata dalla chiave della proprietà. Per informazioni su come lo schema della descrizione delle proprietà influisce sulla formattazione del valore, vedere gli argomenti seguenti:

In genere, la PROPDESC_FORMAT_FLAGS viene usata per modificare il formato previsto dalla descrizione della proprietà.

La stringa di output può contenere caratteri direzionali Unicode. Questi caratteri nonpacing influiscono sull'algoritmo bidirezionale Unicode in modo che i valori vengano visualizzati correttamente quando viene disegnato un linguaggio LTR (left-to-right) in una finestra RTL (RTL) da destra a sinistra o un RTL viene disegnato in una finestra LTR. Questi caratteri includono quanto segue: "\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 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 accodati 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 Energy	Ad esempio, "500 bpcs".
System.Photo.ExposureBias	Ad esempio, "-2 passaggio", " 0 passaggio" o "+3 passaggio".
System.Computer.DecoratedFreeSpace	Ad esempio, "105 MB gratuiti di 13,2 GB".
System.ItemType	Ad esempio, "Applicazione" o "Immagine JPEG".
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 della proprietà in uno degli schemi delle 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 il valore predefinito. Ad esempio, "11/13/2006 3:22 PM".
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 uno spazio singolo.
VT_VECTOR \| Nulla	Valori separati da punti e virgola. Un punto e virgola viene usato indipendentemente dalle impostazioni locali.

Esempio

L'esempio seguente, da includere come parte di un programma più grande, illustra come usare PSFormatPropertyValue per formattare un valore di classificazione.

// IPropertyStore *pStore;
// Assume the variable pps is initialized and valid.
IPropertyDescription *pPropDesc;

HRESULT hr = PSGetPropertyDescription(PKEY_Rating, IID_PPV_ARGS(&pPropDesc));

if (SUCCEEDED(hr))
{
    PWSTR pszValue;

    hr = PSFormatPropertyValue(pStore, pPropDesc, PDFF_DEFAULT, &pszValue);

    if (SUCCEEDED(hr))
    {
        // pszValue contains a formatted string similar to "3 stars".
        CoTaskMemFree(pszValue);
    }
    pPropDesc->Release();
}

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

PSFormatForDisplayAlloc

Schema Descrizione proprietà

Condividi tramite