PropVariantToString, fonction (propvarutil.h)

Article
08/25/2023

Extrait une valeur de chaîne d’une structure PROPVARIANT .

Syntaxe

PSSTDAPI PropVariantToString(
  [in]  REFPROPVARIANT propvar,
  [out] PWSTR          psz,
  [in]  UINT           cch
);

Paramètres

[in] propvar

Type : REFPROPVARIANT

Référence à une structure PROPVARIANT source.

[out] psz

Type : PWSTR

Pointe vers une mémoire tampon de chaîne. Lorsque cette fonction est retournée, la mémoire tampon est initialisée avec une valeur de chaîne Unicode terminée par NULL .

[in] cch

Type : UINT

Taille de la mémoire tampon pointée par psz, en caractères.

Valeur retournée

Type : HRESULT

Cette fonction peut retourner l’une de ces valeurs.

Code de retour	Description
S_OK	La valeur a été extraite et la mémoire tampon de résultat a été terminée par null .
STRSAFE_E_INSUFFICIENT_BUFFER	L’opération de copie a échoué en raison d’un espace de mémoire tampon insuffisant. La mémoire tampon de destination contient une version tronquée et terminée par un caractère Null du résultat prévu. Dans les situations où la troncation est acceptable, cela ne peut pas nécessairement être considéré comme une condition de défaillance.
Une autre valeur d’erreur	L’extraction a échoué pour une autre raison.

Notes

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. 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é une 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 extrait la chaîne et la place dans la mémoire tampon fournie. 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 et définit psz sur « \0 ». Pour obtenir la liste des conversions possibles, consultez PropVariantChangeType . Notez que VT_EMPTY est correctement convertie en « ».

En plus de la valeur NULL de fin, au plus les caractères cch-1 sont écrits dans la mémoire tampon vers laquelle pointe psz. Si la valeur dans la source PROPVARIANT est plus longue que celle qui sera insérée dans la mémoire tampon, une copie terminée PAR NULL tronquée de la chaîne est écrite dans la mémoire tampon et cette fonction retourne STRSAFE_E_INSUFFICIENT_BUFFER. La chaîne résultante est toujours terminée par null .

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.

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

if (SUCCEEDED(hr))

{

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

    // PropVariantToString will convert VT_EMPTY to "".

    // The application decided that it only needs the first 127 characters of the title, so the buffer 

    // has size 128 to account for the terminating NULL.

    WCHAR szTitle[128];

    hr = PropVariantToString(propvar, szTitle, ARRAYSIZE(szTitle));

    if (SUCCEEDED(hr) || hr == STRSAFE_E_INSUFFICIENT_BUFFER)

    {

        // szTitle is now valid and contains up to 127 characters from propvar and a terminating NULL

    }

    else

    {

        // the extraction failed

    }

    PropVariantClear(&propvar);

}

Spécifications


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