Funzione PropVariantToString (propvarutil.h)

Articolo
08/25/2023

Estrae un valore stringa da una struttura PROPVARIANT .

Sintassi

PSSTDAPI PropVariantToString(
  [in]  REFPROPVARIANT propvar,
  [out] PWSTR          psz,
  [in]  UINT           cch
);

Parametri

[in] propvar

Tipo: REFPROPVARIANT

Riferimento a una struttura PROPVARIANT di origine.

[out] psz

Tipo: PWSTR

Punta a un buffer di stringa. Quando questa funzione restituisce, il buffer viene inizializzato con un valore stringa Unicode con terminazione NULL .

[in] cch

Tipo: UINT

Dimensioni del buffer puntate da psz, in caratteri.

Valore restituito

Tipo: HRESULT

Questa funzione può restituire uno di questi valori.

Codice restituito	Descrizione
S_OK	Il valore è stato estratto e il buffer dei risultati è stato terminato NULL .
STRSAFE_E_INSUFFICIENT_BUFFER	L'operazione di copia non è riuscita a causa di spazio buffer insufficiente. Il buffer di destinazione contiene una versione troncata e terminata null del risultato previsto. In situazioni in cui il troncamento è accettabile, questo potrebbe non essere necessariamente considerato come una condizione di errore.
Un altro valore di errore	L'estrazione non è riuscita per qualche altro motivo.

Commenti

Questa funzione helper viene usata in posizioni in cui l'applicazione chiamante prevede che un OGGETTO PROPVARIANT contenga un valore stringa. Ad esempio, un'applicazione che ottiene valori da un archivio proprietà può usare questa opzione per estrarre in modo sicuro un valore stringa per le proprietà stringa.

Se l'origine PROPVARIANT ha tipo VT_LPWSTR o VT_BSTR, questa funzione estrae la stringa e la inserisce nel buffer fornito. In caso contrario, tenta di convertire il valore nella struttura PROPVARIANT in una stringa. Se una conversione non è possibile, PropVariantToString restituirà un codice di errore e imposta psz su '\0'. Per un elenco di possibili conversioni, vedere PropVariantChangeType . Nota, VT_EMPTY viene convertito correttamente in "".

Oltre alla terminazione NULL, al massimo i caratteri cch-1 vengono scritti nel buffer a cui fa riferimento psz. Se il valore nell'origine PROPVARIANT è più lungo di quello che verrà inserito nel buffer, viene scritta una copia terminata NULL troncata della stringa nel buffer e questa funzione restituisce STRSAFE_E_INSUFFICIENT_BUFFER. La stringa risultante verrà sempre terminata null .

Oltre alle conversioni fornite da PropVariantChangeType, i casi speciali seguenti si applicano a PropVariantToString.

Gli elementi PROPVARIANTcon valori vettoriali vengono convertiti in stringhe separando ogni elemento con "; ". Ad esempio, PropVariantToString 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 i valori di VT_UNKNOWN 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

L'esempio seguente, da includere come parte di un programma più ampio, illustra come usare PropVariantToString per accedere a un valore stringa in un PROPVARIANT.

// 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.

    // PropVariantToString will convert VT_EMPTY to "".

    // The application decided that it only needs the first 127 characters of the title, so the buffer 

    // has size 128 to account for the terminating NULL.

    WCHAR szTitle[128];

    hr = PropVariantToString(propvar, szTitle, ARRAYSIZE(szTitle));

    if (SUCCEEDED(hr) || hr == STRSAFE_E_INSUFFICIENT_BUFFER)

    {

        // szTitle is now valid and contains up to 127 characters from propvar and a terminating NULL

    }

    else

    {

        // the extraction failed

    }

    PropVariantClear(&propvar);

}

Requisiti


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