IMAPIAdviseSink::OnNotify

Article
04/04/2023

S’applique à : Outlook 2013 | Outlook 2016

Répond à une notification en effectuant une ou plusieurs tâches. Les tâches effectuées dépendent du type d’événement et de l’objet qui génère la notification.

ULONG OnNotify(
  ULONG cNotif,
  LPNOTIFICATION lpNotifications
);

Paramètres

cNotif

[in] Nombre de structures NOTIFICATION pointées vers le paramètre lpNotifications .

lpNotifications

[in] Pointeur vers une ou plusieurs structures NOTIFICATION qui fournissent des informations sur les événements qui se sont produits.

Valeur renvoyée

S_OK

La notification a été traitée avec succès.

Remarques

Le processus de notification démarre lorsqu’un client ou MAPI effectue un appel à la méthode Advise d’un fournisseur de services pour s’inscrire afin de recevoir une notification d’un type particulier pour un objet particulier. L’un des paramètres de la méthode Advise est un pointeur vers un objet récepteur de conseil qui implémente l’interface IMAPIAdviseSink . Lorsqu’un événement se produit pour l’objet cible qui correspond à la notification inscrite, le fournisseur de services, directement ou indirectement via MAPI, appelle la méthode OnNotify du récepteur de conseil.

L’appel à OnNotify peut se produire pendant l’appel MAPI à l’origine de l’événement ou ultérieurement. Sur les systèmes qui prennent en charge plusieurs threads d’exécution, OnNotify peut être appelé sur le même thread utilisé pour l’inscription ou sur un thread différent. Les clients peuvent s’assurer que l’appel OnNotify est effectué sur le même thread que celui utilisé pour appeler Advise en créant le récepteur de conseil qu’ils passent à Advise avec la fonction HrThisThreadAdviseSink .

Le paramètre lpNotifications pointe vers une ou plusieurs structures NOTIFICATION qui décrivent ce qui a changé pendant l’événement. Il existe un type différent de structure NOTIFICATION pour chaque type d’événement.

Le tableau suivant répertorie les valeurs utilisées pour représenter les types d’événements possibles et les structures associées à chaque valeur :

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
fnevSearchComplete	OBJECT_NOTIFICATION
fnevTableModified	TABLE_NOTIFICATION
fnevStatusObjectModified	STATUS_OBJECT_NOTIFICATION
fnevExtended	EXTENDED_NOTIFICATION

Pour plus d’informations sur la configuration et l’arrêt des notifications, consultez les entrées de référence pour les méthodes Advise et Unadvise pour l’une des interfaces suivantes : IABLogon, IAddrBook, IMAPIForm, IMAPISession, IMAPITable, IMsgStore et IMSLogon.

Pour obtenir des informations générales sur le processus de notification, consultez Notification d’événements dans MAPI.

Remarques pour les responsables de l’implémentation

Votre implémentation OnNotify se compose généralement d’un ou plusieurs blocs de code pour chaque type de notification que vous prévoyez de recevoir. Dans ces blocs de code, effectuez toutes les tâches que vous jugez nécessaires en réponse à la notification. Par exemple, supposons que vous vous inscrivez pour recevoir des notifications fnevObjectModified sur un dossier inclus dans un affichage de boîte de dialogue. Dans le bloc de code que vous incluez dans votre méthode OnNotify pour gérer les notifications fnevObjectModified , vous pouvez envoyer un message Windows à la boîte de dialogue pour demander un affichage mis à jour.

Ne modifiez pas ou ne libérez pas la structure NOTIFICATION transmise à OnNotify. Les données de la structure sont valides uniquement jusqu’à ce que OnNotify retourne.

Remarques pour les appelants

Lorsque des modifications se produisent sur plusieurs objets, vous pouvez notifier un récepteur de conseil inscrit dans un seul appel à OnNotify ou dans plusieurs appels en fonction des contraintes de mémoire. Cela est vrai, que les modifications soient le résultat d’un ou de plusieurs appels de méthode. Par exemple, un appel à IMAPIFolder ::CopyMessages peut affecter plusieurs messages et dossiers. En tant que fournisseur de magasin de messages, vous pouvez effectuer un appel à OnNotify avec un type d’événement fnevObjectModified pour le dossier cible ou plusieurs appels, un pour chaque message affectant. De même, si un client effectue des appels répétés à IMAPIFolder ::CreateMessage, ces appels peuvent être combinés en un événement fnevObjectModified pour le dossier ou séparés en événements fnevObjectCreated individuels pour chaque nouveau message.

Pour plus d’informations sur la façon et le moment de générer des notifications, consultez Notification d’événement dans MAPI et Notification d’événement de prise en charge.