Funzione PropVariantToStringAlloc (propvarutil.h)
Estrae un valore della proprietà stringa da una struttura PROPVARIANT .
Sintassi
PSSTDAPI PropVariantToStringAlloc(
[in] REFPROPVARIANT propvar,
[out] PWSTR *ppszOut
);
Parametri
[in] propvar
Tipo: REFPROPVARIANT
Riferimento a una struttura PROPVARIANT di origine.
[out] ppszOut
Tipo: PWSTR*
Quando questa funzione viene restituita, contiene un puntatore al valore della proprietà estratta, se presente.
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 helper viene usata in posizioni in cui l'applicazione chiamante prevede che un PROPVARIANT contenga un valore stringa.
Se l'origine PROPVARIANT ha tipo VT_LPWSTR o VT_BSTR, questa funzione estrae la stringa in un buffer appena allocato. In caso contrario, tenta di convertire il valore nella struttura PROPVARIANT in una stringa. Se una conversione non è possibile, PropVariantToStringAlloc restituirà un codice di errore e imposterà ppszOut su NULL. Per un elenco delle conversioni possibili, vedere PropVariantChangeType . Si noti che VT_EMPTY viene convertito correttamente in un buffer allocato contenente "".
L'applicazione chiamante è responsabile dell'uso di CoTaskMemFree per rilasciare la stringa a cui punta ppszOut quando non è più necessaria.
Oltre alle conversioni fornite da PropVariantChangeType, i casi speciali seguenti si applicano a PropVariantToStringAlloc.
- I PROPVARIANT con valori vettoriali vengono convertiti in stringhe separando ogni elemento con "; ". Ad esempio, PropVariantToStringAlloc converte un vettore di 3 interi, {3, 1, 4}, nella stringa "3; 1; 4". Il punto e virgola è indipendente dalle impostazioni locali correnti.
- VT_BLOB, VT_STREAM, VT_STREAMED_OBJECT e VT_UNKNOWN valori vengono convertiti in stringhe usando una codifica non supportata. Non è possibile decodificare le stringhe create in questo modo e il formato potrebbe cambiare in futuro.
Esempio
// IPropertyStore *ppropstore;
// Assume variable ppropstore is initialized and valid
PROPVARIANT propvar = {0};
HRESULT hr = ppropstore->GetValue(PKEY_Title, &propvar);
if (SUCCEEDED(hr))
{
// PKEY_Title is expected to produce a VT_LPWSTR or VT_EMPTY value.
// PropVariantToStringAlloc will convert VT_EMPTY to "".
LPWSTR pszTitle;
hr = PropVariantToString(propvar, &pszTitle);
if (SUCCEEDED(hr))
{
// pszTitle is now valid
}
else
{
// pszTitle is always NULL
}
PropVariantClear(&propvar);
}
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows XP con SP2, Windows Vista [solo app desktop] |
| Server minimo supportato | Windows Server 2003 con SP1 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | propvarutil.h |
| Libreria | Propsys.lib |
| DLL | Propsys.dll (versione 6.0 o successiva) |
| Componente ridistribuibile | Windows Desktop Search (WDS) 3.0 |