IABLogon::Advise
S’applique à : Outlook 2013 | Outlook 2016
Inscrit l’appelant pour recevoir une notification des événements spécifiés qui affectent un conteneur, un utilisateur de messagerie ou une liste de distribution.
HRESULT Advise(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG FAR * 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 de l’objet sur lequel les notifications doivent être générées.
ulEventMask
[in] Masque de bits 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. Le tableau suivant répertorie les valeurs valides pour le paramètre ulEventMask et les structures associées à chaque valeur.
| Type d’événement de notification | Structure NOTIFICATION correspondante |
|---|---|
|
fnevCriticalError |
ERROR_NOTIFICATION |
|
fnevObjectCreated |
OBJECT_NOTIFICATION |
|
fnevObjectDeleted |
OBJECT_NOTIFICATION |
|
fnevObjectModified |
OBJECT_NOTIFICATION |
|
fnevObjectCopied |
OBJECT_NOTIFICATION |
|
fnevObjectMoved |
OBJECT_NOTIFICATION |
lpAdviseSink
[in] Pointeur vers un objet récepteur qui conseille de recevoir les notifications suivantes.
lpulConnection
[out] Pointeur vers une valeur différente 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
L’identificateur d’entrée passé dans le paramètre lpEntryID n’est pas au format approprié.
MAPI_E_NO_SUPPORT
Le fournisseur de carnet d’adresses ne prend pas en charge la notification, peut-être parce qu’il n’autorise pas les modifications apportées à ses objets.
MAPI_E_UNKNOWN_ENTRYID
Le fournisseur de carnet d’adresses ne peut pas gérer l’identificateur d’entrée passé dans lpEntryID.
Remarques
Les fournisseurs de carnets d’adresses implémentent la méthode IABLogon ::Advise pour inscrire l’appelant pour qu’il soit averti lorsqu’une modification se produit sur un objet dans l’un de leurs conteneurs. Les appelants peuvent s’inscrire aux notifications concernant les utilisateurs de messagerie, les listes de distribution ou les conteneurs entiers.
Les clients appellent généralement la méthode IAddrBook ::Advise pour s’inscrire aux notifications de carnet d’adresses. MAPI appelle ensuite la méthode Advise du fournisseur de carnet d’adresses responsable de l’objet représenté par l’identificateur d’entrée dans lpEntryID.
Lorsqu’une modification se produit sur l’objet indiqué du type représenté dans ulEventMask, un appel est effectué à la méthode OnNotify du récepteur de conseil vers lequel pointe lpAdviseSink. Les données passées dans la structure NOTIFICATION à la routine OnNotify décrivent l’événement.
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 :
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 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 IABLogon ::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 la méthode Unadvise n’a pas été appelée.
Remarques pour les appelants
Le pointeur de récepteur de conseil que vous transmettez au paramètre lpAdviseSink à Advise peut pointer vers un objet que vous avez créé ou que MAPI a créé via la fonction HrThisThreadAdviseSink . Vous pouvez utiliser HrThisThreadAdviseSink si vous prenez en charge plusieurs threads d’exécution et souhaitez être sûr que les appels suivants à votre méthode OnNotify se produisent à un moment approprié sur un thread approprié.
Préparez-vous à ce que votre objet récepteur de conseil soit libéré à tout moment après votre appel à Conseiller et avant votre appel à Unadvise. Par conséquent, 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 l’utilisation des méthodes IMAPISupport pour prendre en charge la notification, consultez Prise en charge de la notification d’événement. Pour plus d’informations sur le multithreading et MAPI, consultez Threading in MAPI.