IMSLogon::Advise
S’applique à : Outlook 2013 | Outlook 2016
Inscrit un objet auprès d’un fournisseur de magasin de messages pour les notifications relatives aux modifications apportées à la banque de messages. La banque de messages envoie ensuite des notifications sur les modifications apportées à l’objet inscrit.
HRESULT Advise(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG FAR * lpulConnection
);
Paramètres
cbEntryID
[in] Taille, en octets, de l’identificateur d’entrée pointé par le paramètre lpEntryID .
lpEntryID
[in] Pointeur vers l’identificateur d’entrée de l’objet sur lequel les notifications doivent être générées. Cet objet peut être un dossier, un message ou tout autre objet dans la banque de messages. Si MAPI définit le paramètre cbEntryID sur 0 et passe null pour lpEntryID, le récepteur de conseil fournit des notifications sur les modifications apportées à l’ensemble de la banque de messages.
ulEventMask
[in] Masque d’événement des types d’événements de notification qui se produisent pour l’objet sur lequel MAPI génère des notifications. Le masque filtre les cas spécifiques. Chaque type d’événement est associé à une structure qui contient des informations supplémentaires sur l’événement. Le tableau suivant répertorie les types d’événements possibles ainsi que leurs structures correspondantes.
| Type d’événement de notification | Structure correspondante |
|---|---|
| fnevCriticalError |
ERROR_NOTIFICATION |
| fnevNewMail |
NEWMAIL_NOTIFICATION |
| fnevObjectCreated |
OBJECT_NOTIFICATION |
| fnevObjectDeleted |
OBJECT_NOTIFICATION |
| fnevObjectModified |
OBJECT_NOTIFICATION |
| fnevObjectCopied |
OBJECT_NOTIFICATION |
| fnevObjectMoved |
OBJECT_NOTIFICATION |
| fnevSearchComplete |
OBJECT_NOTIFICATION |
| fnevStatusObjectModified |
STATUS_OBJECT_NOTIFICATION |
lpAdviseSink
[in] Pointeur vers un objet récepteur de conseil à appeler lorsqu’un événement se produit pour l’objet de session sur lequel la notification a été demandée. Cet objet récepteur de conseil doit déjà exister.
lpulConnection
[out] Un pointeur vers une variable qui, lors d’un retour réussi, contient le numéro de connexion pour l’inscription de notification. Le numéro de connexion doit être différent de zéro.
Valeur renvoyée
S_OK
L'appel a r�ussi et a renvoy� la valeur attendue ou les valeurs.
MAPI_E_NO_SUPPORT
L’opération n’est pas prise en charge par MAPI ou par un ou plusieurs fournisseurs de services.
Remarques
Les fournisseurs de magasins de messages implémentent la méthode IMSLogon ::Advise pour inscrire un objet pour les rappels de notification. Chaque fois qu’une modification se produit sur l’objet indiqué, 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 ultérieurement. 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 gérer en toute sécurité un appel à OnNotify qui peut se produire à une heure inopportune, une application cliente doit utiliser la fonction HrThisThreadAdviseSink .
Pour fournir des notifications, le fournisseur de magasins de messages qui implémente Advise doit conserver une copie du pointeur vers l’objet récepteur de conseil lpAdviseSink ; pour ce faire, le fournisseur 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 IMSLogon ::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 fournisseurs doivent être prêts à libérer l’objet récepteur advise. Par conséquent, un fournisseur doit libérer son objet récepteur de conseil après les retours d’Advise , sauf s’il a 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.