Notification d’événement dans MAPI

S’applique à : Outlook 2013 | Outlook 2016

La notification d’événement est la communication d’informations entre deux objets MAPI. Par le biais de l’un des objets, un client ou un fournisseur de services s’inscrit pour la notification d’une modification ou d’une erreur, appelée événement, qui peut avoir lieu dans l’autre objet. Une fois que l’événement s’est produit, le premier objet est averti de la modification ou de l’erreur. L’objet qui reçoit la notification est appelé récepteur de conseil ; l’objet responsable de la notification est appelé source de conseil.

Il existe trois types d’objets récepteur de conseil (tous les types sont des objets MAPI standard) :

• Conseiller les objets récepteurs.
• Le formulaire conseille les objets récepteurs.
• Afficher les objets récepteurs conseillés.

Les objets récepteurs d’avis sont le type le plus courant. Les récepteurs De conseil sont généralement implémentés par les applications clientes pour recevoir des notifications de carnet d’adresses et de magasin de messages et prendre en charge l’interface IMAPIAdviseSink : IUnknown . IMAPIAdviseSink contient une seule méthode, IMAPIAdviseSink ::OnNotify. Les récepteurs d’avis de formulaire et d’affichage sont moins courants ; ils sont implémentés pour recevoir des notifications sur les modifications apportées aux formulaires personnalisés. Les récepteurs de conseils de formulaire prennent en charge l’interface IMAPIFormAdviseSink : L’interface IUnknown et les récepteurs de conseil d’affichage prennent en charge l’interface IMAPIViewAdviseSink : IUnknown . Étant donné que la plupart des clients implémentent des objets récepteurs de notification standard, supposons que les discussions des notifications concernent les notifications de carnet d’adresses et de magasin de messages plutôt que les notifications par formulaire. Pour plus d’informations sur les notifications de formulaires, consultez Notifications Forms MAPI et Écriture de code de serveur de formulaires.

Les objets source d’avis sont implémentés par les fournisseurs de services et par MAPI. Tous les fournisseurs de services ne prennent pas en charge la notification d’événements ; elle est facultative, mais fortement recommandée. Les fournisseurs de magasins de messages et de carnets d’adresses prennent généralement en charge les notifications d’objets sur plusieurs de leurs objets et les notifications de table sur leurs tables de contenu et de hiérarchie. Les fournisseurs de transport ne prennent pas en charge les notifications directement ; ils s’appuient sur d’autres méthodes de communication avec les clients.

Contrairement aux récepteurs de conseil, les objets source de conseil ne sont pas un type unique d’objet MAPI. De nombreux objets MAPI, tels que les magasins de messages et les tables, peuvent prendre le rôle de source de conseil. Une source d’avertissement est tout objet MAPI qui effectue les opérations suivantes :

• Implémente une méthode Advise pour recevoir des inscriptions de notification.

• Implémente une méthode Unadvise pour recevoir les annulations de notification.

• Génère des notifications du type approprié aux objets récepteurs conseillés appropriés qui ont été inscrits en appelant leurs méthodes IMAPIAdviseSink ::OnNotify .

Les clients qui implémentent des objets récepteurs de conseil appellent Conseille lorsqu’ils souhaitent s’inscrire à une notification, dans la plupart des cas en passant l’identificateur d’entrée de l’objet avec lequel l’inscription doit avoir lieu, et annuler l’avertissement lorsqu’ils souhaitent annuler l’inscription. Les clients passent un paramètre à Conseiller qui indique les différents types d’événements qu’ils souhaitent surveiller. Advise renvoie un nombre différent de zéro qui représente une connexion réussie entre le récepteur de conseil et la source de conseil.

Avant d’appeler Advise, les clients peuvent déterminer si un fournisseur de magasin de messages prend en charge la notification en vérifiant que l’indicateur STORE_NOTIFY_OK est défini dans la propriété PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) de la banque de messages. Il n’existe aucun moyen pour les clients de déterminer à l’avance si un fournisseur de carnets d’adresses prend en charge les notifications. Les clients doivent tenter de s’inscrire et, si la tentative échoue, ils peuvent supposer que les notifications ne sont pas prises en charge.

Lorsqu’un événement pour lequel un client s’est inscrit se produit, la source de conseil avertit le récepteur de conseil en appelant sa méthode IMAPIAdviseSink ::OnNotify avec une structure de données de notification qui contient des informations sur l’événement. L’implémentation d’OnNotify par un récepteur de conseil peut effectuer des tâches en réponse à la notification, telles que la mise à jour des données en mémoire ou l’actualisation d’un écran.

Les fournisseurs de services peuvent implémenter la prise en charge des notifications manuellement ou tirer parti de l’aide fournie dans trois méthodes IMAPISupport ::Subscribe, IMAPISupport ::Unsubscribe et IMAPISupport ::Notify. Les méthodes Subscribe et Unsubscribe gèrent l’inscription et la désinscription des notifications pour les fournisseurs ; La méthode Notify gère l’envoi de notifications le cas échéant.

Pour utiliser les méthodes d’objet de support pour l’inscription de notification, les fournisseurs de services appellent IMAPISupport ::Subscribe dans leurs méthodes Advise et passent à Subscribe le pointeur récepteur de conseil que les clients passent à Advise. Si un identificateur d’entrée est passé en tant que paramètre d’entrée pour spécifier une source de conseil, les fournisseurs de services le convertissent en clé binaire. L’abonnement crée un numéro de connexion unique et c’est ce numéro que les fournisseurs de services retournent aux clients. Les fournisseurs de services peuvent libérer le pointeur d’objet récepteur de conseil du client à tout moment une fois l’appel Advise terminé.

Lorsque les clients appellent Unadvise pour annuler une inscription, les fournisseurs de services décrémentent le compte de référence sur le pointeur récepteur de conseil du client ou appellent Unsubscribe pour faire de même.

Lorsqu’il est temps de générer une notification, les fournisseurs de services effectuent tout traitement interne lié à la notification et initialisent une structure NOTIFICATION en définissant tous ses membres inutilisés sur zéro. Cette technique d’initialisation de la structure NOTIFICATION peut aider les clients à créer des implémentations OnNotify plus petites, plus rapides et moins sujettes aux erreurs.

L’illustration suivante montre la communication entre les objets récepteur de conseil, les objets source et MAPI. MAPI est impliqué uniquement lorsque la source de conseil appelle les méthodes IMAPISupport pour la prise en charge des notifications.

Appels de notification d’événement

La classe CAdviseSink MFCMAPI (à l’aide des fichiers AdviseSink.h et AdviseSink.cpp) implémente l’objet récepteur advise pour tous les appels à Advise. Pour plus d’informations sur MFCMAPI, consultez MFCMAPI en tant qu’exemple de code et MFCMAPI.