PropVariantToStrRet, fonction (propvarutil.h)

Article
03/01/2024

Extrait une chaîne d’une structure PROPVARIANT et la place dans une structure STRRET .

Syntaxe

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

Paramètres

[in] propvar

Type : REFPROPVARIANT

Référence à une structure PROPVARIANT source.

[out] pstrret

Type : STRRET*

Pointe vers la structure STRRET . Lorsque cette fonction est retournée, la structure a été initialisée pour contenir une copie de la chaîne extraite.

Valeur retournée

Type : HRESULT

Si cette fonction réussit, elle retourne S_OK. Sinon, elle retourne un code d’erreur HRESULT.

Remarques

Cette fonction d’assistance est utilisée dans les applications qui souhaitent convertir une valeur de chaîne dans une structure PROPVARIANT en structure STRRET . Par instance, une application implémentant IShellFolder ::GetDisplayNameOf peut trouver cette fonction utile.

Si la source PROPVARIANT a le type VT_LPWSTR ou VT_BSTR, cette fonction extrait la chaîne et la place dans la structure STRRET . Sinon, il tente de convertir la valeur de la structure PROPVARIANT en chaîne. Si une conversion n’est pas possible, PropVariantToString retourne un code d’échec. Pour obtenir la liste des conversions possibles, consultez PropVariantChangeType . Notez que VT_EMPTY est correctement converti en « ».

Outre les conversions fournies par PropVariantChangeType, les cas spéciaux suivants s’appliquent à PropVariantToString.

Les PROPVARIANTà valeur vectorielle sont convertis en chaînes en séparant chaque élément à l’aide de « ; ». Par exemple, PropVariantToString convertit un vecteur de 3 entiers, {3, 1, 4}, en chaîne « 3 ; 1; 4". Le point-virgule est indépendant des paramètres régionaux actuels.
les valeurs VT_BLOB, VT_STREAM, VT_STREAMED_OBJECT et VT_UNKNOWN sont converties en chaînes à l’aide d’un encodage non pris en charge. Il n’est pas possible de décoder les chaînes créées de cette façon et le format peut changer à l’avenir.

Si l’extraction réussit, la fonction initialise le membre uType de la structure STRRET avec STRRET_WSTR et définit le membre pOleStr de cette structure pour qu’il pointe vers une copie allouée de la chaîne. L’application appelante est chargée d’utiliser CoTaskMemFree ou StrRetToStr pour libérer cette chaîne quand elle n’est plus nécessaire.

Exemples

L’exemple suivant, à inclure dans le cadre d’un programme plus large, montre comment utiliser PropVariantToString pour accéder à une valeur de chaîne dans 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);

}

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP avec SP2, Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 avec SP1 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	propvarutil.h
Bibliothèque	Propsys.lib
DLL	Propsys.dll (version 6.0 ou ultérieure)
Composant redistribuable	Windows Desktop Search (WDS) 3.0