Fonction PropVariantGetStringElem (propvarutil.h)

Article
03/01/2024

Extrait un seul élément de chaîne Unicode d’une structure PROPVARIANT de type VT_LPWSTR, VT_BSTR VT_VECTOR | VT_LPWSTR, VT_VECTOR | VT_BSTR ou VT_ARRAY | VT_BSTR.

Syntaxe

PSSTDAPI PropVariantGetStringElem(
  [in]  REFPROPVARIANT propvar,
  [in]  ULONG          iElem,
  [out] PWSTR          *ppszVal
);

Paramètres

[in] propvar

Type : REFPROPVARIANT

Référence à une structure PROPVARIANT source.

[in] iElem

Type : ULONG

L’index vectoriel ou de tableau ; sinon, iElem doit être 0.

[out] ppszVal

Type : PWSTR*

Lorsque cette fonction retourne, contient la valeur de chaîne extraite. L’application appelante est chargée de libérer cette chaîne en appelant CoTaskMemFree quand elle n’est plus nécessaire.

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 fonctionne pour les structures PROPVARIANT des types suivants :

VT_LPWSTR
VT_BSTR
VT_VECTOR | VT_LPWSTR
VT_VECTOR | VT_BSTR
VT_ARRAY | VT_BSTR

Si la propriété PROPVARIANT source a le type VT_LPWSTR ou VT_BSTR, iElem doit avoir la valeur 0. Sinon, iElem doit être inférieur au nombre d’éléments dans le vecteur ou le tableau. Vous pouvez utiliser PropVariantGetElementCount pour obtenir le nombre d’éléments dans le vecteur ou le tableau.

Si un élément BSTR a un pointeur NULL , cette fonction alloue une chaîne vide.

Exemples

L’exemple de code suivant, à inclure dans le cadre d’un programme plus grand, montre comment utiliser PropVariantGetStringElem avec une instruction d’itération pour accéder aux valeurs d’un PROPVARIANT.

// PROPVARIANT propvar;
// Assume the variable propvar is initialized and valid

if ((propvar.vt & VT_TYPEMASK) == VT_LPWSTR || (propvar.vt & VT_TYPEMASK) == VT_BSTR)
{
    UINT cElem = PropVariantGetElementCount(propvar);
    HRESULT hr = <mark type="const">S_OK</mark>;

    for (UINT iElem = 0; SUCCEEDED(hr) && iElem < cElem; iElem ++)
    {
        PWSTR pszValue;
        hr = PropVariantGetStringElem(propvar, iElem, &pszValue);

        if (SUCCEEDED(hr))
        {
            // pszValue is valid now
            CoTaskMemFree(pszValue);
        }
    }
}

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

Voir aussi

PropVariantGetElem

Partager via