Funzione PropVariantToStrRet (propvarutil.h)

Articolo
08/25/2023

Estrae una stringa da una struttura PROPVARIANT e la inserisce in una struttura STRRET .

Sintassi

PSSTDAPI PropVariantToStrRet(
  [in]  REFPROPVARIANT propvar,
  [out] STRRET         *pstrret
);

Parametri

[in] propvar

Tipo: REFPROPVARIANT

Riferimento a una struttura PROPVARIANT di origine.

[out] pstrret

Tipo: STRRET*

Punta alla struttura STRRET . Quando questa funzione restituisce, la struttura è stata inizializzata per contenere una copia della stringa estratta.

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 nelle applicazioni che desiderano convertire un valore stringa in una struttura PROPVARIANT in una struttura STRRET . Ad esempio, un'applicazione che implementa IShellFolder::GetDisplayNameOf può trovare questa funzione utile.

Se l'origine PROPVARIANT ha tipo VT_LPWSTR o VT_BSTR, questa funzione estrae la stringa e la inserisce nella struttura STRRET . 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. Per un elenco di possibili conversioni, vedere PropVariantChangeType . Nota, VT_EMPTY viene convertito correttamente in "".

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.

Se l'estrazione ha esito positivo, la funzione inizializza il membro uType della struttura STRRET con STRRET_WSTR e imposta il membro pOleStr di tale struttura per puntare a una copia allocata della stringa. L'applicazione chiamante è responsabile dell'uso di CoTaskMemFree o StrRetToStr per liberare questa stringa quando non è più necessaria.

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_FileName, &propvar);

if (SUCCEEDED(hr))

{

    // PKEY_FileName is expected to produce a VT_LPWSTR or VT_EMPTY value.

    // PropVariantToStrRet will convert VT_EMPTY to "".

    // If this were an implementation of IShellFolder::GetDisplayNameOf, strName would be a parameter and the caller would free the memory associated with the STRRET

    STRRET strName;

    hr = PropVariantToStrRet(propvar, &strName);

    if (SUCCEEDED(hr))

    {

        // strName is now valid

 

        if (strName.uType == STRRET_WSTR)

        {

            CoTaskMemFree(strName.pOleStr);

        }

    }

    else

    {

        // the extraction failed

    }

    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