PropVariantToStringVector, fonction (propvarutil.h)

Article
03/01/2024

Extrait un vecteur de chaînes d’une structure PROPVARIANT .

Syntaxe

PSSTDAPI PropVariantToStringVector(
  [in]  REFPROPVARIANT propvar,
  [out] PWSTR          *prgsz,
  [in]  ULONG          crgsz,
  [out] ULONG          *pcElem
);

Paramètres

[in] propvar

Type : REFPROPVARIANT

Référence à une structure PROPVARIANT source.

[out] prgsz

Type : PWSTR*

Pointeur vers un vecteur de pointeurs de chaîne. Lorsque cette fonction retourne, la mémoire tampon a été initialisée avec des éléments pcElem pointant vers des chaînes nouvellement allouées contenant les données extraites de la source PROPVARIANT.

[in] crgsz

Type : ULONG

Taille de la mémoire tampon pointée par prgsz, dans les éléments.

[out] pcElem

Type : ULONG*

Lorsque cette fonction retourne, contient le nombre de chaînes extraites 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.
TYPE_E_BUFFERTOOSMALL	La sourcePROPVARIANT contenait plus de valeurs crgsz . Mémoire tampon pointée par prgsz.
E_INVALIDARG	LePROPVARIANT n’était pas du type approprié.

Remarques

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 avec un nombre fixe d’éléments.

Cette fonction fonctionne pour les types PROPVARIANT 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 d’assistance extrait jusqu’aux valeurs de chaîne crgsz et place une copie allouée de chacune d’elles dans la mémoire tampon vers laquelle pointe prgsz. Si PROPVARIANT contient plus d’éléments que ne le fera tenir dans la mémoire tampon prgsz , cette fonction retourne une erreur et définit pcElem sur 0.

Étant donné que chaque chaîne dans pointée par la mémoire tampon de sortie a été nouvellement allouée, l’application appelante est responsable de l’utilisation de CoTaskMemFree pour libérer chaque chaîne dans la mémoire tampon de sortie quand elles ne sont plus nécessaires.

Si un BSTR dans le PROPVARIANT source a la valeur NULL, il est converti en une chaîne nouvellement allouée contenant « » dans la sortie.

Exemples

// PROPVARIANT propvar;
// Assume the variable propvar is initialized and valid
LPWSTR rgszStrings; // The application is expecting propvar to hold 4 strings in a vector
ULONG cElems;
HRESULT hr = PropVariantToStringVector(propvar, rgszStrings, ARRAYSIZE(rgszStrings), &cElems);
if (SUCCEEDED(hr))
{
     if (cElems == ARRAYSIZE(rgszStrings))
     {
         // The application got 4 string which are now stored in rgszStrings
     }
     else
     {
         // The application got cElems which are stored in the first cElems elements of rgLongs
     }
 
    // Free the cElems strings that PropVariantToStringVector allocated
    for (ULONG i = 0; i < cElems; i++)
    {
        CoTaskMemFree(rgszStrings[i]);
    }
}

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