Funzione PropVariantToStringAlloc (propvarutil.h)

Articolo
03/01/2024

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