Funzione PSFormatPropertyValue (propsys.h)
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":
|
| System.Photo.ISOSpeed | Ad esempio, "ISO-400". |
| System.Photo.ShutterSpeed |
Il valore APEX viene convertito in un tempo di esposizione usando questa formula:
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:
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 |