PropVariantToBSTR, fonction (propvarutil.h)

Article
03/01/2024

Extrait la valeur de propriété BSTR d’une structure PROPVARIANT .

Syntaxe

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

Paramètres

[in] propvar

Type : REFPROPVARIANT

Référence à une structure PROPVARIANT source.

[out] pbstrOut

Type : BSTR*

Pointeur vers la valeur de propriété extraite s’il en existe une ; sinon, contient une chaîne vide.

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 endroits où l’application appelante s’attend à ce qu’un PROPVARIANT contienne une valeur de chaîne.

Si la source PROPVARIANT a le type VT_BSTR ou VT_LPWSTR, cette fonction extrait la chaîne en tant que valeur BSTR . Sinon, il tente de convertir la valeur de la structure PROPVARIANT en chaîne. Si une conversion n’est pas possible, PropVariantToBSTR retourne un code d’échec et définit pbstrOut sur NULL. Pour obtenir la liste des conversions possibles, consultez PropVariantChangeType .

VT_EMPTY est correctement converti en un BSTR alloué contenant « ».

L’application appelante est responsable de l’utilisation de SysFreeString pour libérer le BSTR pointé par pbstrOut lorsqu’il n’est plus nécessaire.

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

Les PROPVARIANTs à valeur vectorielle sont convertis en chaînes en séparant chaque élément à l’aide de « ; ». Par exemple, PropVariantToBSTR 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 via 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.

Exemples

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

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