PropVariantToStringVectorAlloc, fonction (propvarutil.h)

Article
08/25/2023

Extrait des données d’une structure PROPVARIANT dans des chaînes nouvellement allouées dans un vecteur nouvellement alloué.

Syntaxe

PSSTDAPI PropVariantToStringVectorAlloc(
  [in]  REFPROPVARIANT propvar,
  [out] PWSTR          **pprgsz,
  [out] ULONG          *pcElem
);

Paramètres

[in] propvar

Type : REFPROPVARIANT

Référence à une structure PROPVARIANT source.

[out] pprgsz

Type : PWSTR**

Lorsque cette fonction retourne, contient un pointeur vers un vecteur de chaînes extraites de la structure PROPVARIANT source.

[out] pcElem

Type : ULONG*

Lorsque cette fonction est retournée, contient le nombre d’éléments de chaîne extraits de la structure PROPVARIANT source.

Valeur retournée

Type : HRESULT

Cette fonction peut retourner l’une de ces valeurs.

Code de retour	Description
S_OK	Retourne S_OK en cas de réussite, ou une valeur d’erreur dans le cas contraire.
E_INVALIDARG	Le PROPVARIANT n’était pas du type approprié.

Notes

Cette fonction d’assistance est utilisée dans les endroits où l’application appelante s’attend à ce qu’un PROPVARIANT contienne un vecteur de valeurs de chaîne.

Cette fonction d’assistance fonctionne pour les typesPROPVARIANT suivants :

VT_VECTOR | VT_LPWSTR
VT_VECTOR | VT_BSTR
VT_ARRAY | VT_BSTR

Si la source PROPVARIANT a un type pris en charge, cette fonction extrait un vecteur de valeurs de chaîne dans un vecteur nouvellement alloué de chaînes nouvellement allouées. L’application appelante est responsable de l’utilisation de CoTaskMemFree pour libérer à la fois les chaînes contenues dans le vecteur de sortie et le vecteur de sortie lui-même, lorsqu’elles ne sont plus nécessaires.

Si un BSTR dans la source PROPVARIANT a la valeur NULL, cette fonction place une chaîne nouvellement allouée contenant « » dans le vecteur de sortie.

Exemples

L’exemple suivant, à inclure dans le cadre d’un programme plus large, montre comment utiliser PropVariantToStringVectorAlloc pour accéder à une valeur de vecteur de chaîne dans un PROPVARIANT.

// IPropertyStore *ppropstore;
// Assume variable ppropstore is initialized and valid
PROPVARIANT propvar = {0};
HRESULT hr = ppropstore->GetValue(PKEY_Keywords, &propvar);
if (SUCCEEDED(hr))
{
         // PKEY_Keywords is expected to produce a VT_VECTOR | VT_LPWSTR, or VT_EMPTY
         // PropVariantToStringVectorAlloc will return an error for VT_EMPTY
         LPWSTR *prgKeywords;
         ULONG cElem;
         hr = PropVariantToStringVectorAlloc (propvar, &prgKeywords, &cElem);
         if (SUCCEEDED(hr))
         {
                 // prgKeywords contains cElem strings
                 for (ULONG i = 0; i < cElem; i++)
                 {
                          CoTaskMemFree(prgKeywords[i]);
                 }
                 CoTaskMemFree(prgKeywords);
         }
         else
         {
                 // propvar either is VT_EMPTY, or contains something other than a vector of  strings
         }
         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