IPerPropertyBrowsing ::GetPredefinedStrings, méthode (ocidl.h)

Article
08/25/2023

Récupère les chaînes de description d’un tableau pour les valeurs autorisées que la propriété spécifiée peut accepter.

Syntaxe

HRESULT GetPredefinedStrings(
  [in]  DISPID     dispID,
  [out] CALPOLESTR *pCaStringsOut,
  [out] CADWORD    *pCaCookiesOut
);

Paramètres

[in] dispID

Identificateur de dispatch de la propriété.

[out] pCaStringsOut

Pointeur vers une structure de tableau comptabilisée allouée par l’appelant qui contient le nombre d’éléments et l’adresse d’un tableau de pointeurs de chaîne alloué par méthode. Cette méthode alloue également de la mémoire pour les valeurs de chaîne contenant les noms prédéfinis et stocke les pointeurs de chaîne dans le tableau. Si la méthode échoue, aucune mémoire n’est allouée et le contenu de la structure n’est pas défini.

[out] pCaCookiesOut

Pointeur vers la structure de tableau allouée par l’appelant qui contient le nombre d’éléments et l’adresse d’un tableau alloué par méthode de valeurs DWORD . Les valeurs du tableau peuvent être passées à IPerPropertyBrowsing ::GetPredefinedValue pour récupérer la valeur associée au nom dans la même position de tableau dans pCaStringsOut. Si la méthode échoue, aucune mémoire n’est allouée et le contenu de la structure n’est pas défini.

Valeur retournée

Cette méthode peut retourner les valeurs de retour standard E_INVALIDARG, E_OUTOFMEMORY et E_UNEXPECTED, ainsi que les valeurs suivantes.

Code de retour	Description
S_OK	La commande s'est correctement terminée.
E_NOTIMPL	Cette méthode n’est pas implémentée et les noms prédéfinis ne sont pas pris en charge.
E_POINTER	L’adresse dans pCaStringsOut ou pCaCookiesOut n’est pas valide. Par exemple, l’un ou l’autre des paramètres peut être NULL.

Remarques

Chaque chaîne retournée dans le tableau pointé vers pCaStringsOut a un jeton correspondant dans le tableau compté pointé vers pCaCookiesOut, où le jeton peut être passé à IPerPropertyBrowsing ::GetPredefinedValue pour obtenir la valeur réelle (un VARIANT) correspondant à la chaîne.

À l’aide des chaînes prédéfinies, un appelant peut obtenir une liste de chaînes pour remplir des éléments d’interface utilisateur, tels qu’une zone de liste déroulante. Lorsque l’utilisateur final sélectionne l’une de ces chaînes comme valeur à affecter à une propriété, l’appelant peut ensuite obtenir la valeur correspondante via IPerPropertyBrowsing ::GetPredefinedValue.

Remarques aux appelants

Les structures CALPOLESTR et CADWORD passées à cette méthode sont toutes deux allouées par l’appelant. L’appelant est chargé de libérer chaque chaîne pointée vers du tableau CALPOLESTR ainsi que de la structure CALPOLESTR .

Toute la mémoire est allouée avec CoTaskMemAlloc. L’appelant est chargé de libérer les chaînes et le tableau avec CoTaskMemFree.

Au retour de cette méthode, l’appelant est responsable de toute cette mémoire et doit la libérer quand elle n’est plus nécessaire. Le code pour y parvenir s’affiche comme suit.

CALPOLESTR     castr; 
CWDWORD        cadw; 
ULONG          i; 
 
pIPerPropertyBrowsing-&gt;GetPredefinedStrings(dispID, &amp;castr, &amp;cadw); 
 
//...Use the strings and the cookies 
 
CoTaskMemFree((void *)cadw.pElems); 
 
for (i=0; i &lt; castr.cElems; i++) 
    CoTaskMemFree((void *)castr.pElems[i]); 
 
CoTaskMemFree((void *)castr.pElems);

Remarques aux implémenteurs

La prise en charge des noms et des valeurs prédéfinis n’est pas requise. Si votre objet ne prend pas en charge ces noms, retournez E_NOTIMPL à partir de cette méthode. Si cette méthode n’est pas implémentée, IPerPropertyBrowsing ::GetPredefinedValue ne doit pas non plus être implémenté.

Cette méthode remplit les membres cElems et pElems des structures CADWORD et CALPOLESTR . Il alloue les tableaux pointés par ces structures avec CoTaskMemAlloc et remplit ces tableaux. Dans le cas CALPOLESTR , cette méthode alloue également chaque chaîne avec CoTaskMemAlloc, en stockant chaque pointeur de chaîne dans le tableau.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	ocidl.h