Méthode IDispatch ::GetIDsOfNames (oaidl.h)

Article
03/04/2024

Mappe un seul membre et un ensemble facultatif de noms d’arguments à un ensemble correspondant de DISPID entiers, qui peuvent être utilisés lors des appels ultérieurs à Invoke. La fonction dispatch DispGetIDsOfNames fournit une implémentation standard de GetIDsOfNames.

Syntaxe

HRESULT GetIDsOfNames(
  [in]  REFIID   riid,
  [in]  LPOLESTR *rgszNames,
  [in]  UINT     cNames,
  [in]  LCID     lcid,
  [out] DISPID   *rgDispId
);

Paramètres

[in] riid

Réservé à un usage ultérieur. Doit être IID_NULL.

[in] rgszNames

Tableau de noms à mapper.

[in] cNames

Compte des noms à mapper.

[in] lcid

Contexte des paramètres régionaux dans lequel interpréter les noms.

[out] rgDispId

Tableau alloué par l’appelant, chaque élément de contenant un identificateur (ID) correspondant à l’un des noms passés dans le tableau rgszNames. Le premier élément représente le nom du membre. Les éléments suivants représentent chacun des paramètres du membre.

Valeur retournée

Cette méthode peut retourner l’une de ces valeurs.

Code de retour	Description
S_OK	Réussite.
E_OUTOFMEMORY	Mémoire insuffisante.
DISP_E_UNKNOWNNAME	Un ou plusieurs des noms spécifiés n’étaient pas connus. Le tableau de DISPIDs retourné contient DISPID_UNKNOWN pour chaque entrée qui correspond à un nom inconnu.
DISP_E_UNKNOWNLCID	L’identificateur de paramètres régionaux (LCID) n’a pas été reconnu.

Remarques

Une implémentation IDispatch peut associer n’importe quelle valeur d’ID d’entier positif à un nom donné. Zéro est réservé à la propriété par défaut ou Value ; –1 est réservé pour indiquer un nom inconnu ; et d’autres valeurs négatives sont définies à d’autres fins. Par exemple, si GetIDsOfNames est appelé et que l’implémentation ne reconnaît pas un ou plusieurs des noms, elle retourne DISP_E_UNKNOWNNAME et le tableau rgDispId contient des DISPID_UNKNOWN pour les entrées qui correspondent aux noms inconnus.

Les DISPID de membre et de paramètre doivent rester constants pendant toute la durée de vie de l’objet. Cela permet à un client d’obtenir les DISPID une seule fois et de les mettre en cache pour une utilisation ultérieure.

Lorsque GetIDsOfNames est appelé avec plusieurs noms, le prénom (rgszNames[0]) correspond au nom du membre, et les noms suivants correspondent aux noms des paramètres du membre.

Le même nom peut être mappé à différents DISPID, selon le contexte. Par exemple, un nom peut avoir un DISPID lorsqu’il est utilisé comme nom de membre avec une interface particulière, un ID différent en tant que membre d’une autre interface et un mappage différent pour chaque fois qu’il apparaît en tant que paramètre.

GetIDsOfNames est utilisé lorsqu’un client IDispatch est lié à des noms au moment de l’exécution. Pour établir une liaison au moment de la compilation, un client IDispatch peut mapper des noms à des DISPID à l’aide des interfaces d’informations de type décrites dans Interfaces de description de type. Cela permet à un client de lier des membres au moment de la compilation et d’éviter d’appeler GetIDsOfNames au moment de l’exécution. Pour obtenir une description de la liaison au moment de la compilation, consultez Interfaces de description de type.

L’implémentation de GetIDsOfNames ne respecte pas la casse. Les utilisateurs qui ont besoin d’un mappage de noms respectant la casse doivent utiliser des interfaces d’informations de type pour mapper les noms aux DISPID, plutôt que d’appeler GetIDsOfNames.

Attention Vous ne pouvez pas utiliser cette méthode pour accéder aux valeurs qui ont été ajoutées dynamiquement, telles que les valeurs ajoutées via JavaScript. Utilisez plutôt le GetDispID de l’interface IDispatchEx. Pour plus d’informations, consultez l’interface IDispatchEx.

Exemples

Le code suivant de l’exemple de fichier Lines Lines.cpp implémente la fonction membre GetIDsOfNames pour la classe CLine. L’objet ActiveX ou OLE utilise l’implémentation standard DispGetIDsOfNames. Cette implémentation s’appuie sur DispGetIdsOfNames pour valider les arguments d’entrée. Pour réduire les risques de sécurité, incluez du code qui effectue une validation plus robuste des arguments d’entrée.

STDMETHODIMP 
CLine::GetIDsOfNames(
      REFIID riid,
      OLECHAR ** rgszNames,
      UINT cNames,
      LCID lcid,
      DISPID * rgDispId)
{
      return DispGetIDsOfNames(m_ptinfo, rgszNames, cNames, rgDispId);
}

Le code suivant peut apparaître dans un client ActiveX qui appelle GetIDsOfNames pour obtenir le DISPID de la propriété CLineColor .

HRESULT hresult;
IDispatch * pdisp = (IDispatch *)NULL;
DISPID dispid;
OLECHAR * szMember = "color";

// Code that sets a pointer to the dispatch (pdisp) is omitted.

hresult = pdisp->GetIDsOfNames(
   IID_NULL,
   &szMember,
   1, LOCALE_SYSTEM_DEFAULT,
   &dispid);