IMsgStore::Advise
S’applique à : Outlook 2013 | Outlook 2016
S’inscrit pour recevoir une notification des événements spécifiés qui affectent la banque de messages.
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 dossier ou du message sur lequel les notifications doivent être générées, ou null. Si lpEntryID est défini sur NULL, Advise s’inscrit pour les notifications sur l’ensemble de la banque de messages.
ulEventMask
[in] Masque de valeurs qui indiquent les types d’événements de notification qui intéressent l’appelant et doivent être inclus dans l’inscription. Une structure NOTIFICATION correspondante est associée à chaque type d’événement qui contient des informations sur l’événement. 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 au fournisseur de magasin de messages particulier.
fnevNewMail
S’inscrit aux notifications relatives à l’arrivée de nouveaux messages.
fnevObjectCreated
S’inscrit aux notifications relatives à la création d’un dossier ou d’un message.
fnevObjectCopied
S’inscrit aux notifications concernant un dossier ou un message en cours de copie.
fnevObjectDeleted
S’inscrit aux notifications concernant la suppression d’un dossier ou d’un message.
fnevObjectModified
S’inscrit aux notifications concernant un dossier ou un message en cours de modification.
fnevObjectMoved
S’inscrit aux notifications concernant un dossier ou un message 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.
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 numéro de connexion différent de zéro qui représente la connexion entre l’objet récepteur de conseil de l’appelant et la banque de messages.
Valeur renvoyée
S_OK
L’inscription a réussi.
MAPI_E_NO_SUPPORT
Le fournisseur de magasin de messages ne prend pas en charge l’inscription pour la notification via la banque de messages.
Remarques
La méthode IMsgStore ::Advise établit une connexion entre l’objet récepteur de conseil de l’appelant et la banque de messages ou un objet dans la banque de messages. Cette connexion est utilisée pour envoyer des notifications au récepteur de notification lorsqu’un ou plusieurs événements, comme spécifié dans le paramètre ulEventMask , se produisent sur l’objet source de conseil. Lorsque le paramètre lpEntryID pointe vers un identificateur d’entrée valide, la source conseillée est l’objet identifié par cet identificateur d’entrée. Lorsque lpEntryID a la valeur NULL, la source de conseil est la banque de messages.
Pour envoyer une notification, le fournisseur de magasin de messages ou MAPI appelle la méthode IMAPIAdviseSink ::OnNotify du récepteur de notification 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 responsables de l’implémentation
Vous pouvez prendre en charge la notification avec ou sans l’aide de MAPI. MAPI a trois méthodes d’objet de prise en charge pour aider les fournisseurs de services à implémenter la notification : IMAPISupport ::Subscribe, IMAPISupport ::Unsubscribe et IMAPISupport ::Notify. Si vous choisissez d’utiliser les méthodes de prise en charge MAPI, appelez Subscribe lorsque votre méthode Advise est appelée et relâchez le pointeur lpAdviseSink .
Si vous choisissez de prendre en charge la notification vous-même, appelez la méthode IUnknown ::AddRef du récepteur de conseil représenté par le paramètre lpAdviseSink pour conserver une copie de ce pointeur. Conservez cette copie jusqu’à ce que votre méthode IMsgStore ::Unadvise soit appelée pour annuler l’inscription.
Quelle que soit la façon dont vous prenez en charge la notification, attribuez un numéro de connexion différent de zéro à l’inscription de notification et retournez-le dans le paramètre lpulConnection . Ne relâchez pas ce numéro de connexion tant que l’option Unadvise n’a pas été appelée et n’est pas terminée.
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 devez être certain que les notifications se produisent uniquement à un moment particulier sur un thread particulier, appelez la fonction HrThisThreadAdviseSink pour générer l’objet récepteur de conseil que vous passez à Advise.
Une fois qu’un appel à Advise a réussi et que l’option Unadvise a été appelée pour annuler l’inscription, préparez-vous à libérer l’objet récepteur advise. Vous devez libérer votre objet récepteur de conseil après les retours d’Advise , sauf si vous avez une utilisation à long terme spécifique pour celui-ci.
Pour plus d’informations sur le 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 IMsgStore ::Advise pour s’inscrire aux notifications sur l’ensemble de la banque de messages. |