IMAPITable::Advise

S’applique à : Outlook 2013 | Outlook 2016

Inscrit un objet récepteur conseille de recevoir une notification des événements spécifiés affectant la table.

HRESULT Advise(
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG_PTR FAR * lpulConnection
);

Paramètres

ulEventMask

[in] Valeur indiquant le type d’événement qui générera la notification. Seule la valeur suivante est valide :

fnevTableModified

lpAdviseSink

[in] Pointeur vers un objet récepteur de conseil pour recevoir les notifications suivantes. Cet objet récepteur de conseil doit avoir déjà été alloué.

lpulConnection

[out] Pointeur vers une valeur différente de zéro qui représente l’inscription de notification réussie.

Valeur renvoyée

S_OK

L’inscription de notification s’est terminée avec succès.

MAPI_E_NO_SUPPORT

L’implémentation de la table ne prend pas en charge les modifications apportées à ses lignes et colonnes ou ne prend pas en charge la notification.

Remarques

Utilisez la méthode IMAPITable ::Advise pour inscrire un objet table implémenté dans le fournisseur pour les rappels de notification. Chaque fois qu’une modification se produit dans l’objet table, le fournisseur vérifie le bit du masque d’événement qui a été défini dans le paramètre ulEventMask et, par conséquent, le type de modification qui s’est produit. Si un bit est défini, le fournisseur appelle la méthode IMAPIAdviseSink ::OnNotify pour l’objet sink advise indiqué par le paramètre lpAdviseSink pour signaler l’événement. Les données transmises dans la structure de notification à la routine OnNotify décrivent l’événement.

L’appel à OnNotify peut se produire pendant l’appel qui modifie l’objet, ou à tout moment suivant. Sur les systèmes qui prennent en charge plusieurs threads d’exécution, l’appel à OnNotify peut se produire sur n’importe quel thread. Pour transformer un appel à OnNotify qui peut se produire à un moment inopportune en un appel plus sûr à gérer, un fournisseur doit utiliser la fonction HrThisThreadAdviseSink .

Pour fournir des notifications, le fournisseur qui implémente Advise doit conserver une copie du pointeur vers l’objet récepteur lpAdviseSink advise ; pour ce faire, il appelle la méthode IUnknown ::AddRef pour que le récepteur de conseil conserve son pointeur d’objet jusqu’à ce que l’inscription de la notification soit annulée avec un appel à la méthode IMAPITable ::Unadvise . L’implémentation Advise doit affecter un numéro de connexion à l’inscription de notification et appeler AddRef sur ce numéro de connexion avant de le retourner dans le paramètre lpulConnection . Les fournisseurs de services peuvent libérer l’objet récepteur de conseil avant l’annulation de l’inscription, mais ils ne doivent pas libérer le numéro de connexion tant que l’option Unadvise n’a pas été appelée.

Une fois qu’un appel à Advise a réussi et avant l’appel de l’option Unadvise , les clients doivent être prêts à libérer l’objet récepteur de conseil. Un client doit donc libérer son objet récepteur de conseil après le retour de Advise , sauf s’il a une utilisation à long terme spécifique pour celui-ci.

En raison du comportement asynchrone de la notification, les implémentations qui modifient les paramètres de colonne de table peuvent recevoir des notifications avec des informations organisées dans un ordre de colonne précédent. Par instance, une ligne de table peut être retournée pour un message qui vient d’être supprimé du conteneur. Une telle notification est envoyée lorsque la modification du paramètre de colonne a été apportée et que des informations le concernant ont été envoyées, mais que la vue de la table de notification n’a pas encore été mise à jour avec ces informations.

Pour plus d’informations sur le processus de notification, consultez Notification d’événements dans MAPI. Pour plus d’informations sur la notification de table, consultez À propos des notifications de table. Pour plus d’informations sur l’utilisation des méthodes IMAPISupport pour prendre en charge la notification, consultez Prise en charge de la notification d’événement.

Référence MFCMAPI

Pour voir un exemple de code MFCMAPI, consultez le tableau suivant.

Fichier	Fonction	Commentaire
ContentsTableListCtrl.cpp	CContestTableListCtrl ::NotificationOn	MFCMAPI utilise la méthode IMAPITable ::Advise pour s’inscrire aux notifications afin de permettre à l’affichage de table de rester à jour.

Voir aussi

HrThisThreadAdviseSink
IMAPIAdviseSink::OnNotify
IMAPITable::Unadvise
TABLE_NOTIFICATION
IMAPITable : IUnknownMFCMAPI en tant qu’exemple de code