IMAPISession::Advise
S’applique à : Outlook 2013 | Outlook 2016
S’inscrit pour recevoir la notification des événements spécifiés qui affectent la session.
HRESULT Advise(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG_PTR lpulConnection
);
Paramètres
cbEntryID
[in] Nombre d’octets dans l’identificateur d’entrée vers lequel pointe le paramètre lpEntryID .
lpEntryID
[in] Pointeur vers l’identificateur d’entrée du carnet d’adresses ou de l’objet de magasin de messages sur les notifications à générer, ou NULL, qui indique que le client s’inscrit pour recevoir des notifications sur les événements qui affectent uniquement la session.
ulEventMask
[in] Masque de valeurs qui indiquent les types d’événements de notification qui intéressent le client et doivent être inclus dans l’inscription. Si lpEntryID a la valeur NULL, MAPI inscrit automatiquement le client pour les événements d’erreur critiques qui affectent uniquement la session. Lorsque lpEntryID pointe vers un identificateur d’entrée, les valeurs suivantes sont valides pour le paramètre ulEventMask :
fnevCriticalError
S’inscrit aux notifications concernant les erreurs graves, telles que la mémoire insuffisante.
fnevExtended
S’inscrit aux notifications relatives aux événements spécifiques à un fournisseur de carnet d’adresses ou de magasin de messages particulier et à l’arrêt de session.
fnevNewMail
S’inscrit aux notifications relatives à l’arrivée de nouveaux messages.
fnevObjectCreated
S’inscrit pour les notifications relatives à la création d’un nouvel objet.
fnevObjectCopied
S’inscrit pour les notifications relatives à un objet en cours de copie.
fnevObjectDeleted
S’inscrit pour les notifications relatives à la suppression d’un objet.
fnevObjectModified
S’inscrit pour les notifications relatives à un objet en cours de modification.
fnevObjectMoved
S’inscrit pour les notifications relatives à un objet en cours de déplacement.
fnevSearchComplete
S’inscrit aux notifications sur la fin d’une opération de recherche.
lpAdviseSink
[in] Pointeur vers un objet récepteur qui conseille de recevoir les notifications suivantes. Cet objet récepteur de conseil doit avoir déjà été alloué.
lpulConnection
[out] Pointeur vers un nombre différent de zéro qui représente la connexion entre l’objet récepteur de conseil de l’appelant et la session.
Valeur renvoyée
S_OK
L’inscription a réussi.
MAPI_E_INVALID_ENTRYID
L’identificateur d’entrée pointé par lpEntryID ne représente pas un identificateur d’entrée valide.
MAPI_E_NO_SUPPORT
Le fournisseur de services responsable de l’identificateur d’entrée pointé par lpEntryID ne prend pas en charge le type d’événements spécifié dans le paramètre ulEventMask ou ne prend pas en charge la notification.
MAPI_E_UNKNOWN_ENTRYID
L’identificateur d’entrée pointé par lpEntryID ne peut pas être géré par les fournisseurs de services dans le profil.
Remarques
La méthode IMAPISession ::Advise établit une connexion entre l’objet récepteur de conseil de l’appelant, la session et, éventuellement, un fournisseur de services. Cette connexion est utilisée pour envoyer des notifications au récepteur de notification lorsqu’un ou plusieurs événements spécifiés dans le paramètre ulEventMask se produisent à l’objet pointé par lpEntryID. Lorsque lpEntryID a la valeur NULL, l’objet cible est la session et les notifications sont envoyées uniquement pour les erreurs critiques et les événements étendus.
Lorsque lpEntryID pointe vers un identificateur d’entrée valide, MAPI appelle la méthode Advise de l’objet d’ouverture de session qui appartient au fournisseur de services responsable. Par exemple, si lpEntryID pointe vers l’identificateur d’entrée d’une liste de distribution, MAPI appelle la méthode IABLogon ::Advise du fournisseur de carnet d’adresses approprié.
Pour envoyer une notification, le fournisseur de services ou MAPI appelle la méthode IMAPIAdviseSink ::OnNotify du récepteur de conseil inscrit. L’un des paramètres de OnNotify, une structure de notification, contient des informations qui décrivent l’événement spécifique.
Remarques pour les appelants
Sur les systèmes qui prennent en charge plusieurs threads d’exécution, l’appel à OnNotify peut également se produire sur n’importe quel thread à tout moment. Si vous avez besoin d’être certain que les notifications n’auront lieu qu’à un moment donné sur un thread particulier, appelez la fonction HrThisThreadAdviseSink pour générer l’objet récepteur de conseil que vous passez à la méthode Advise .
Pour déterminer quand un client s’est déconnecté, inscrivez-vous aux notifications dans votre fournisseur de services en appelant Advise avec lpEntryID défini sur NULL et cbEntryID défini sur 0. Lorsque la fermeture de session se produit, vous recevez une notification fnevExtended.
Une fois qu’un appel à Advise a réussi et que IMAPISession ::Unadvise a été appelé pour annuler l’inscription, relâchez votre objet récepteur de conseil, sauf si vous avez une utilisation à long terme spécifique pour celui-ci.
Pour obtenir une vue d’ensemble du processus de notification, consultez Notification d’événements dans MAPI.
Pour plus d’informations sur la gestion des notifications, consultez Gestion des notifications.
Référence MFCMAPI
Pour voir un exemple de code MFCMAPI, consultez le tableau suivant.
| Fichier | Fonction | Commentaire |
|---|---|---|
| BaseDialog.cpp |
CBaseDialog ::OnNotificationsOn |
MFCMAPI utilise la méthode IMAPISession ::Advise pour s’inscrire aux notifications sur la session. |