IAddrBook::Advise
S’applique à : Outlook 2013 | Outlook 2016
Inscrit un client ou un fournisseur de services pour recevoir des notifications concernant les modifications apportées à une ou plusieurs entrées dans le carnet d’adresses.
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 conteneur de carnet d’adresses, de l’utilisateur de messagerie ou de la liste de distribution qui génère une notification lorsqu’une modification se produit du ou des types décrits dans le paramètre ulEventMask .
ulEventMask
[in] Un ou plusieurs événements de notification que l’appelant s’inscrit pour recevoir. Chaque événement est associé à une structure de notification particulière qui contient des informations sur la modification qui s’est produite. Le tableau suivant répertorie les valeurs valides pour ulEventMask et leurs structures correspondantes.
| Événement de notification | Structure correspondante |
|---|---|
|
fnevCriticalError |
ERROR_NOTIFICATION |
|
fnevObjectCreated |
OBJECT_NOTIFICATION |
|
fnevObjectDeleted |
OBJECT_NOTIFICATION |
|
fnevObjectModified |
OBJECT_NOTIFICATION |
|
fnevObjectCopied |
OBJECT_NOTIFICATION |
|
fnevObjectMoved |
OBJECT_NOTIFICATION |
|
fnevTableModified |
TABLE_NOTIFICATION |
lpAdviseSink
[in] Pointeur vers l’objet récepteur de conseil à appeler lorsque l’événement pour lequel la notification a été demandée se produit.
lpulConnection
[out] Pointeur vers un numéro de connexion différent de zéro qui représente l’inscription de notification.
Valeur renvoyée
S_OK
L’inscription de la notification a réussi.
MAPI_E_INVALID_ENTRYID
Le fournisseur de carnet d’adresses responsable de l’identificateur d’entrée passé dans lpEntryID n’a pas pu inscrire de notification pour l’entrée correspondante.
MAPI_E_NO_SUPPORT
La notification n’est pas prise en charge par le fournisseur de carnet d’adresses responsable de l’objet identifié par l’identificateur d’entrée passé dans le paramètre lpEntryID .
MAPI_E_UNKNOWN_ENTRYID
L’identificateur d’entrée passé dans lpEntryID ne peut pas être géré par les fournisseurs de carnets d’adresses dans le profil.
Remarques
Les clients et les fournisseurs de services appellent la méthode Advise pour s’inscrire à un ou plusieurs types de notification sur une entrée de carnet d’adresses. Les types de notification sont indiqués par le masque d’événement passé avec le paramètre ulEventMask .
MAPI transfère cet appel Advise au fournisseur de carnet d’adresses responsable de l’entrée, comme indiqué par l’identificateur d’entrée dans le paramètre lpEntryID . Le fournisseur de carnet d’adresses gère l’inscription lui-même ou appelle la méthode de support IMAPISupport ::Subscribe pour inviter MAPI à inscrire l’appelant. Un numéro de connexion différent de zéro est retourné pour représenter l’inscription réussie.
Chaque fois qu’une modification se produit dans l’entrée du type indiqué par l’inscription de notification, le fournisseur de carnet d’adresses appelle la méthode IMAPIAdviseSink ::OnNotify pour l’objet sink advise spécifié dans le paramètre lpAdviseSink . La méthode OnNotify inclut une structure NOTIFICATION en tant que paramètre d’entrée qui contient des données pour décrire l’événement.
Selon le fournisseur du carnet d’adresses, l’appel à OnNotify peut se produire immédiatement après la modification de l’objet inscrit ou 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. Les clients peuvent demander que ces notifications se produisent sur un thread particulier en appelant la fonction HrThisThreadAdviseSink pour créer l’objet récepteur de conseil passé à Advise.
Étant donné qu’un fournisseur de carnet d’adresses peut libérer l’objet récepteur de conseil transmis par les clients à tout moment après la réussite de l’appel Advise et avant un appel IAddrBook ::Unadvise pour annuler la notification, les clients doivent libérer leurs objets récepteurs de conseil quand Advise est retourné.
Pour plus d’informations sur le processus de notification, consultez Notification d’événements dans MAPI.