Funzione PropVariantToBSTR (propvarutil.h)

Articolo
03/05/2024

Estrae il valore della proprietà BSTR di una struttura PROPVARIANT .

Sintassi

PSSTDAPI PropVariantToBSTR(
  [in]  REFPROPVARIANT propvar,
  [out] BSTR           *pbstrOut
);

Parametri

[in] propvar

Tipo: REFPROPVARIANT

Riferimento a una struttura PROPVARIANT di origine.

[out] pbstrOut

Tipo: BSTR*

Puntatore al valore della proprietà estratta, se presente; in caso contrario, contiene una stringa vuota.

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_BSTR o VT_LPWSTR, questa funzione estrae la stringa come valore BSTR . In caso contrario, tenta di convertire il valore nella struttura PROPVARIANT in una stringa. Se non è possibile eseguire una conversione, PropVariantToBSTR restituisce un codice di errore e imposta pbstrOut su NULL. Per un elenco delle conversioni possibili, vedere PropVariantChangeType .

VT_EMPTY viene convertita correttamente in una stringa BSTR allocata contenente "".

L'applicazione chiamante è responsabile dell'uso di SysFreeString per rilasciare il BSTR a cui punta pbstrOut quando non è più necessario.

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

I PROPVARIANT con valori vettoriali vengono convertiti in stringhe separando ogni elemento con "; ". Ad esempio, PropVariantToBSTR converte un vettore di 3 numeri 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 tramite una codifica non supportata. Non è possibile decodificare le stringhe create in questo modo e il formato potrebbe cambiare in futuro.

Esempio

Nell'esempio seguente, da includere come parte di un programma più ampio, viene illustrato come usare PropVariantToBSTR per accedere a un valore stringa in un PROPVARIANT.

// IPropertyStore *ppropstore;
// Assume the 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.
    // PropVariantToBSTR will convert VT_EMPTY to "".
    BSTR bstrTitle;
    
    hr = PropVariantToBSTR(propvar, &bstrTitle);
    
    if (SUCCEEDED(hr))
    {
        // bstrTitle is now valid.
    }
    else
    {
        // bstrTitle 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

Vedi anche

InitPropVariantFromString

PropVariantGetStringElem

PropVariantToString

PropVariantToStringWithDefault

Condividi tramite