Notification d’événement de prise en charge
S’applique à : Outlook 2013 | Outlook 2016
Étant donné que la prise en charge de la notification d’événements peut être compliquée, MAPI fournit trois méthodes d’objet de support qui implémentent les parties les plus difficiles du processus. Ces méthodes fonctionnent comme une unité, et un fournisseur doit utiliser les trois ou aucune d’entre elles.
Les méthodes de prise en charge MAPI utilisent des clés de notification pour gérer les connexions entre les récepteurs de conseil et les objets qui génèrent les notifications. Une clé de notification est une structure NOTIFKEY qui contient des données binaires qui identifient un objet dans les processus. Une clé de notification est généralement copiée à partir de l’identificateur d’entrée à long terme de l’objet source de conseil. Si le client a fourni un identificateur d’entrée dans l’appel à Conseiller, vous pouvez l’utiliser pour la clé de notification. Si le paramètre lpEntryID de Advise est NULL, utilisez l’identificateur d’entrée de l’objet conteneur le plus externe possible, tel que la banque de messages.
Pour utiliser les méthodes de support, appelez IMAPISupport ::Subscribe chaque fois qu’un client appelle votre méthode Advise pour s’inscrire à une notification. Allouez une structure NOTIFKEY et créez une clé de notification unique pour votre objet source de conseil. Par exemple, un fournisseur de magasin de messages qui est invité à notifier un client lorsqu’un message est reçu dans un dossier particulier crée une clé de notification pour ce dossier. Passez un pointeur vers la structure NOTIFKEY dans l’appel à S’abonner , ainsi qu’un pointeur vers le récepteur de conseil du client. Subscribe appelle la méthode IUnknown ::AddRef du récepteur de conseil pour incrémenter son nombre de références et MAPI conserve le pointeur jusqu’à ce que l’inscription soit annulée.
Vous pouvez transmettre l’indicateur NOTIFY_SYNC à S’abonner pour demander que Notify se comporte de manière synchrone et ne retourne pas tant qu’il n’a pas effectué tous les appels aux méthodes IMAPIAdviseSink ::OnNotify des récepteurs de conseil inscrits. Définissez cet indicateur uniquement pour votre propre usage interne. Ne la définissez pas lorsque vous répondez à un appel de conseil du client. La notification d’événements entre les clients et les fournisseurs est toujours asynchrone. Autrement dit, MAPI garantit que l’appel au cours duquel un événement se produit sera retourné au client avant les appels OnNotify .
Si vous définissez l’indicateur NOTIFY_SYNC, n’apportez aucune modification aux objets récepteur de conseil et ne passez pas un récepteur de conseil wrapper créé par HrThisThreadAdviseSink à Subscribe. HrThisThreadAdviseSink crée une version thread-safe d’un récepteur de conseil à utiliser avec une notification asynchrone uniquement.
Si un récepteur d’avis inscrit pour la notification synchrone retourne à partir d’OnNotify avec l’indicateur CALLBACK_DISCONTINUE défini, IMAPISupport ::Notify définit l’indicateur NOTIFY_CANCELED et retourne sans effectuer d’appel à OnNotify.
Une fois l’abonnement retourné, vous n’aurez plus besoin de conserver votre copie du récepteur de conseil du client. Appelez sa méthode IUnknown ::Release pour la libérer. Subscribe renvoie un numéro de connexion différent de zéro que vous devez retourner au client. Le numéro de connexion représente le lien entre la source de conseil et le récepteur de conseil. Elle reste valide jusqu’à ce que le client effectue un appel réussi à Unadvise.
Lorsque le client est prêt à annuler une inscription, il appelle votre méthode Unadvise . Transmettez le numéro de connexion de l’appel Unadvise à IMAPISupport ::Unsubscribe. Se désabonner appelle la méthode IUnknown ::Release du récepteur de conseil. Comme pour Conseiller et Annuler l’abonnement, les appels à s’abonner et à se désabonner doivent être associés. Vous devez passer un appel à Se désabonner pour chaque appel effectué à l’abonnement. Toutefois, vous n’avez pas besoin d’appeler Subscribe chaque fois que votre méthode Advise est appelée. À l’inverse, vous pouvez l’appeler pour configurer des notifications internes.
Lorsqu’un événement se produit, allouez une ou plusieurs structures NOTIFICATION du type approprié pour l’événement et appelez IMAPISupport ::Notify. Notify génère une notification pour chaque récepteur de conseil inscrit. Vous devez définir tous les membres inutilisés de la structure NOTIFICATION 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.
Notez qu’une structure NOTIFICATION distincte est nécessaire pour chaque événement, même pour plusieurs événements du même type. Par exemple, si trois clients sont inscrits pour la notification de table sur une table particulière et que cinq lignes sont ajoutées à la table, vous devez créer cinq structures OBJECT_NOTIFICATION pour votre appel Notify . Une notification par lot comme celle-ci permet d’obtenir de meilleures performances que l’appel de Notification cinq fois. Pour chaque appel Notify , MAPI appelle la méthode IMAPIAdviseSink ::OnNotify de chaque récepteur de conseil inscrit. S’il n’existe aucun récepteur de conseil inscrit, MAPI ignore l’appel.
Les fournisseurs de services qui envoient des notifications par lot doivent les commander afin qu’elles puissent être interprétées de la première notification à la dernière. Ce classement est particulièrement nécessaire lorsqu’un lot de notification contient une série d’événements, comme TABLE_ROW_ADDED avec un événement qui fait référence à une ligne précédente qui a été ajoutée à un autre événement dans le même lot.