Implémentation d’un objet récepteur Advise

S’applique à : Outlook 2013 | Outlook 2016

Un client peut implémenter ses propres objets récepteurs de conseil ou utiliser une fonction utilitaire, HrAllocAdviseSink. HrAllocAdviseSink crée un objet sink de conseil avec une implémentation de OnNotify qui appelle une fonction de rappel.

L’utilisation de HrAllocAdviseSink présente des avantages et des inconvénients. Il peut enregistrer du travail, mais il ne fournit aucun contrôle sur les références en comptant l’objet récepteur de conseil qu’il crée. Par conséquent, les clients qui doivent contrôler soigneusement la publication de leur récepteur de conseil ou qui ont des interdépendances entre leur récepteur de conseil et un autre objet client doivent construire leur propre implémentation IMAPIAdviseSink et éviter d’utiliser HrAllocAdviseSink complètement.

Un client implémentant son propre récepteur de conseil doit en faire un objet indépendant qui n’est pas lié à d’autres objets ou ne dépend pas de celui-ci afin d’éliminer les complications potentielles dans le comptage des références et la libération d’objets. Toutefois, si vous devez implémenter votre récepteur de conseil dans le cadre d’un autre objet ou inclure un pointeur arrière vers un autre objet en tant que membre de données, il est recommandé de conserver deux nombres de références distincts : un pour l’objet référencé par le récepteur de conseil et un pour le récepteur de conseil.

Lorsque le nombre de références de l’objet référencé tombe à zéro, toutes ses méthodes peuvent échouer et sa vtable peut être détruite, mais la mémoire du récepteur conseillé doit rester intacte jusqu’à ce que son nombre de références tombe également à zéro. Cela signifie que la méthode Release du récepteur conseillé doit décrémenter son nombre de références et terminer la destruction de l’objet lorsque ce nombre atteint zéro. Si deux nombres de références distincts ne sont pas conservés, il serait facile de détruire par inadvertance le récepteur de conseil dans le cadre du processus release de l’objet englobant.

Les clients qui utilisent HrAllocAdviseSink pour implémenter un récepteur de conseil doivent être tout aussi prudents à ne pas inclure leur fonction de rappel en tant que méthode dans un autre objet récepteur de conseil. Pour les clients C++, il est tentant de le faire et de passer ce pointeur en tant que paramètre. Il s’agit d’une stratégie dangereuse, car les clients libèrent généralement un objet lorsque son nombre de références atteint zéro. Libérer la mémoire de l’objet récepteur conseillé rend le pointeur this non valide.

Selon le type d’événement et la source de conseil, votre méthode OnNotify peut gérer les événements de différentes façons. Le tableau suivant fournit des suggestions sur la façon de gérer certains des événements standard.

Type d’événement	Gestion dans OnNotify
Objet déplacé	Si le parent d’origine de l’objet déplacé est lié au nouveau parent, mettez à jour la vue en commençant par le conteneur de dossier ou de carnet d’adresses le plus élevé dans la hiérarchie. Si les deux conteneurs parents ne sont pas liés, mettez à jour leurs deux vues.
Nouveau message	Modifiez l’interface utilisateur pour informer l’utilisateur de l’arrivée d’un ou de plusieurs nouveaux messages. Placez le dossier de réception dans l’affichage actuel.
Erreur	Pour tous les objets à l’exception de la session, enregistrez l’erreur si nécessaire et retournez. Pour l’objet de session, déconnectez-vous si possible.
Recherche terminée	Aucun traitement n’est nécessaire.

Remarque

Les gestionnaires de notification doivent être réentrants.