Fonction PropVariantToStringAlloc (propvarutil.h)
Extrait une valeur de propriété de chaîne d’une structure PROPVARIANT .
Syntaxe
PSSTDAPI PropVariantToStringAlloc(
[in] REFPROPVARIANT propvar,
[out] PWSTR *ppszOut
);
Paramètres
[in] propvar
Type : REFPROPVARIANT
Référence à une structure PROPVARIANT source.
[out] ppszOut
Type : PWSTR*
Lorsque cette fonction retourne, contient un pointeur vers la valeur de propriété extraite, le cas échéant.
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 propriété PROPVARIANT source a le type VT_LPWSTR ou VT_BSTR, cette fonction extrait la chaîne dans une mémoire tampon nouvellement allouée. Sinon, il tente de convertir la valeur de la structure PROPVARIANT en chaîne. Si une conversion n’est pas possible, PropVariantToStringAlloc retourne un code d’échec et définit ppszOut sur NULL. Pour obtenir la liste des conversions possibles, consultez PropVariantChangeType . Notez que VT_EMPTY est correctement converti en mémoire tampon allouée contenant « ».
L’application appelante est responsable de l’utilisation de CoTaskMemFree pour libérer la chaîne pointée par ppszOut lorsqu’elle n’est plus nécessaire.
En plus des conversions fournies par PropVariantChangeType, les cas spéciaux suivants s’appliquent à PropVariantToStringAlloc.
- Les PROPVARIANTs à valeur vectorielle sont convertis en chaînes en séparant chaque élément à l’aide de « ; ». Par exemple, PropVariantToStringAlloc convertit un vecteur de 3 entiers, {3, 1, 4}, en la 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 manière et le format peut changer à l’avenir.
Exemples
// 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.
// PropVariantToStringAlloc will convert VT_EMPTY to "".
LPWSTR pszTitle;
hr = PropVariantToString(propvar, &pszTitle);
if (SUCCEEDED(hr))
{
// pszTitle is now valid
}
else
{
// pszTitle 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 |