PropVariantToStringWithDefault, fonction (propvarutil.h)

Article
03/04/2024

Extrait la valeur de la propriété de chaîne d’une structure PROPVARIANT . Si aucune valeur n’existe, la valeur par défaut spécifiée est retournée.

Syntaxe

PSSTDAPI_(PCWSTR) PropVariantToStringWithDefault(
  [in] REFPROPVARIANT propvarIn,
  [in] LPCWSTR        pszDefault
);

Paramètres

[in] propvarIn

Type : REFPROPVARIANT

Référence à une structure PROPVARIANT source.

[in] pszDefault

Type : LPCWSTR

Pointeur vers une valeur de chaîne Unicode par défaut, pour une utilisation où aucune valeur n’existe actuellement. Peut être NULL.

Valeur retournée

Type : PCWSTR

Retourne la valeur de chaîne ou la valeur par défaut, ou la valeur par défaut.

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 et souhaite utiliser une valeur par défaut si ce n’est pas le cas. Par instance, une application qui obtient des valeurs à partir d’un magasin de propriétés peut l’utiliser pour extraire en toute sécurité la valeur de chaîne pour les propriétés de chaîne.

Si la source PROPVARIANT a le type VT_LPWSTR ou VT_BSTR, cette fonction d’assistance retourne un pointeur vers la valeur dans la source PROPVARIANT. Si la source PROPVARIANT a le type VT_EMPTY ou si une conversion n’est pas possible, PropVariantToStringWithDefault retourne la valeur par défaut fournie par pszDefault.

Notez que cette fonction retourne des pointeurs vers les données fournies dans les paramètres. Par conséquent, l’application doit s’assurer que les données fournies aux paramètres restent valides jusqu’à ce que le résultat ne soit plus utilisé.

Exemples

L’exemple suivant, à inclure dans le cadre d’un programme plus large, montre comment utiliser PropVariantToStringWithDefault 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_Title, &propvar);
if (SUCCEEDED(hr))
{
     // PKEY_Title is expected to produce a VT_LPWSTR or VT_EMPTY value.
     // The application developer decided to treat VT_EMPTY or invalid values as ""
     PCWSTR pszTitle = PropVariantToStringWithDefault(propvar, L"");
     // pszTitle is now valid.
     PropVariantClear(&propvar);
}
// ... later in the program ...
hr = ppropstore->GetValue(PKEY_Comment, &propvar);
if (SUCCEEDED(hr))
{
         // PKEY_Comment is expected to produce a VT_LPWSTR or VT_EMPTY value.
         // The application developer decided to treat VT_EMPTY as NULL
         PCWSTR pszComment = PropVariantToStringWithDefault(propvar, NULL);
         if (pszComment)
         {
                 // pszComment is valid
         }
         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