CConnectionPoint, classe

Définit un type particulier d'interface utilisé pour communiquer avec d'autres objets OLE, appelé « point de connexion ».

Syntaxe

class CConnectionPoint : public CCmdTarget

Membres

Constructeurs publics

Nom	Description
CConnectionPoint ::CConnectionPoint	Construit un objet CConnectionPoint.

Méthodes publiques

Nom	Description
CConnectionPoint ::GetConnections	Récupère tous les points de connexion dans un mappage de connexion.
CConnectionPoint ::GetContainer	Récupère le conteneur du contrôle propriétaire de la carte de connexion.
CConnectionPoint ::GetIID	Récupère l’ID d’interface d’un point de connexion.
CConnectionPoint ::GetMaxConnections	Récupère le nombre maximal de points de connexion pris en charge par un contrôle.
CConnectionPoint ::GetNextConnection	Récupère un pointeur vers l’élément de connexion au pos.
CConnectionPoint ::GetStartPosition	Démarre une itération de carte en retournant une valeur POSITION qui peut être passée à un GetNextConnection appel.
CConnectionPoint ::OnAdvise	Appelé par l’infrastructure lors de l’établissement ou de la rupture des connexions.
CConnectionPoint ::QuerySinkInterface	Récupère un pointeur vers l’interface récepteur demandée.

Notes

Contrairement aux interfaces OLE normales, utilisées pour implémenter et exposer les fonctionnalités d’un contrôle OLE, un point de connexion implémente une interface sortante capable de lancer des actions sur d’autres objets, telles que le déclenchement d’événements et les notifications de modification.

Une connexion se compose de deux parties : l’objet appelant l’interface, appelé « source », et l’objet implémentant l’interface, appelé « récepteur ». En exposant un point de connexion, une source permet aux récepteurs d’établir des connexions à elle-même. Par le biais du mécanisme de point de connexion, un objet source obtient un pointeur vers l’implémentation du récepteur d’un ensemble de fonctions membres. Par exemple, pour déclencher un événement implémenté par le récepteur, la source peut appeler la méthode appropriée de l'implémentation du récepteur.

Par défaut, une COleControlclasse dérivée de -implémente deux points de connexion : un pour les événements et un pour les notifications de modification de propriété. Ces connexions sont utilisées respectivement pour le déclenchement d’événements et pour notifier un récepteur (par exemple, le conteneur du contrôle) lorsqu’une valeur de propriété a changé. La prise en charge est également fournie pour que les contrôles OLE implémentent des points de connexion supplémentaires. Pour chaque point de connexion supplémentaire implémenté dans votre classe de contrôle, vous devez déclarer une « partie de connexion » qui implémente le point de connexion. Si vous implémentez un ou plusieurs points de connexion, vous devez également déclarer une seule « carte de connexion » dans votre classe de contrôle.

L’exemple suivant illustre une carte de connexion simple et un point de connexion pour le Sample contrôle OLE, constitué de deux fragments de code : la première partie déclare la carte de connexion et le point ; la seconde implémente cette carte et ce point. Le premier fragment est inséré dans la déclaration de la classe de contrôle, sous la protected section :

// Connection point for ISample interface
BEGIN_CONNECTION_PART(CMyClass, SampleConnPt)
CONNECTION_IID(IID_ISampleSink)
END_CONNECTION_PART(SampleConnPt)

DECLARE_CONNECTION_MAP()

Les macros BEGIN_CONNECTION_PART et END_CONNECTION_PART déclarent une classe incorporée ( XSampleConnPt dérivée de ) qui implémente ce point de CConnectionPointconnexion particulier. Si vous souhaitez remplacer les CConnectionPoint fonctions membres ou ajouter des fonctions membres de votre choix, déclarez-les entre ces deux macros. Par exemple, la macro CONNECTION_IID remplace la CConnectionPoint::GetIID fonction membre lorsqu’elle est placée entre ces deux macros.

Le deuxième fragment de code est inséré dans le fichier d’implémentation (. CPP) de votre classe de contrôle. Ce code implémente la carte de connexion, qui inclut le point de connexion supplémentaire, SampleConnPt:

BEGIN_CONNECTION_MAP(CMyClass, CCmdTarget)
   CONNECTION_PART(CMyClass, IID_ISampleSink, SampleConnPt)
END_CONNECTION_MAP()

Une fois ces fragments de code insérés, l’exemple de contrôle OLE expose un point de connexion pour l’interface ISampleSink .

En règle générale, les points de connexion prennent en charge la « multidiffusion », c’est-à-dire la possibilité de diffuser sur plusieurs récepteurs connectés à la même interface. Le fragment de code suivant montre comment effectuer la multidiffusion en itérant à travers chaque récepteur sur un point de connexion :

void CMyClass::CallSinkFunc()
{
   POSITION pos = m_xSampleConnPt.GetStartPosition();
   ISampleSink *pSampleSink;
   while (pos != NULL)
   {
      pSampleSink = (ISampleSink *)(m_xSampleConnPt.GetNextConnection(pos));
      if (pSampleSink != NULL)
      {
         pSampleSink->SinkFunc();
      }
   }
}

Cet exemple récupère l'ensemble actuel de connexions sur le point de connexion SampleConnPt par un appel à CConnectionPoint::GetConnections. Il effectue ensuite une itération via les connexions et appelle ISampleSink::SinkFunc chaque connexion active.

Pour plus d’informations sur l’utilisation CConnectionPoint, consultez l’article Points de connexion.

Hiérarchie d'héritage

CObject

CCmdTarget

CConnectionPoint

Spécifications

En-tête : afxdisp.h

CConnectionPoint ::CConnectionPoint

Construit un objet CConnectionPoint.

CConnectionPoint();

CConnectionPoint ::GetConnections

Appelez cette fonction pour récupérer toutes les connexions actives pour un point de connexion.

const CPtrArray* GetConnections();

Valeur de retour

Pointeur vers un tableau de connexions actives (récepteurs). Certains des pointeurs du tableau peuvent être NULL. Chaque pointeur non NULL de ce tableau peut être converti en un pointeur vers l’interface récepteur à l’aide d’un opérateur de cast.

CConnectionPoint ::GetContainer

Appelé par l’infrastructure pour récupérer le IConnectionPointContainer point de connexion.

virtual LPCONNECTIONPOINTCONTAINER GetContainer();

Valeur de retour

En cas de réussite, un pointeur vers le conteneur ; sinon NULL.

Notes

Cette fonction est généralement implémentée par la macro BEGIN_CONNECTION_PART.

CConnectionPoint ::GetIID

Appelé par l’infrastructure pour récupérer l’ID d’interface d’un point de connexion.

virtual REFIID GetIID() = 0;

Valeur de retour

Référence à l’ID d’interface du point de connexion.

Notes

Remplacez cette fonction pour retourner l’ID d’interface de ce point de connexion.

CConnectionPoint ::GetMaxConnections

Appelé par l’infrastructure pour récupérer le nombre maximal de connexions prises en charge par le point de connexion.

virtual int GetMaxConnections();

Valeur de retour

Nombre maximal de connexions prises en charge par le contrôle, ou -1 si aucune limite n’est atteinte.

Notes

L’implémentation par défaut retourne -1, indiquant aucune limite.

Remplacez cette fonction si vous souhaitez limiter le nombre de récepteurs pouvant se connecter à votre contrôle.

CConnectionPoint ::GetNextConnection

Récupère un pointeur vers l’élément de connexion au pos.

LPUNKNOWN GetNextConnection(POSITION& pos) const;

Paramètres

pos
Spécifie une référence à une valeur POSITION retournée par un appel précédent GetNextConnection ou GetStartPosition .

Valeur de retour

Pointeur vers l’élément de connexion spécifié par pos ou NULL.

Notes

Cette fonction est particulièrement utile pour effectuer une itération sur tous les éléments de la carte de connexion. Lors de l’itération, ignorez les valeurs NULL retournées par cette fonction.

Exemple

void CMyClass::CallSinkFunc()
{
   POSITION pos = m_xSampleConnPt.GetStartPosition();
   ISampleSink *pSampleSink;
   while (pos != NULL)
   {
      pSampleSink = (ISampleSink *)(m_xSampleConnPt.GetNextConnection(pos));
      if (pSampleSink != NULL)
      {
         pSampleSink->SinkFunc();
      }
   }
}

CConnectionPoint ::GetStartPosition

Démarre une itération de carte en retournant une valeur POSITION qui peut être passée à un appel GetNextConnection .

POSITION GetStartPosition() const;

Valeur de retour

Valeur POSITION qui indique une position de départ pour itérer la carte ; ou NULL si la carte est vide.

Notes

La séquence d’itération n’est pas prévisible ; par conséquent, le « premier élément de la carte » n’a aucune signification particulière.

Exemple

Consultez l’exemple de CConnectionPoint ::GetNextConnection.

CConnectionPoint ::OnAdvise

Appelé par l’infrastructure lorsqu’une connexion est établie ou interrompue.

virtual void OnAdvise(BOOL bAdvise);

Paramètres

bAdvise
TRUE, si une connexion est établie ; sinon FALSE.

Notes

L'implémentation par défaut n'exécute aucune opération.

Remplacez cette fonction si vous souhaitez recevoir une notification lorsque les récepteurs se connectent ou se déconnectent de votre point de connexion.

CConnectionPoint ::QuerySinkInterface

Récupère un pointeur vers l’interface récepteur demandée.

virtual HRESULT QuerySinkInterface(
    LPUNKNOWN pUnkSink,
    void** ppInterface);

Paramètres

pUnkSink
Identificateur de l’interface récepteur demandée.

ppInterface
Pointeur vers le pointeur d’interface identifié par pUnkSink. Si l’objet ne prend pas en charge cette interface, * ppInterface est défini sur NULL.

Valeur de retour

Valeur HRESULT standard.

Voir aussi

CCmdTarget, classe
Graphique hiérarchique