IMAPIAdviseSink::OnNotify

项目
04/04/2023

适用于：Outlook 2013 | Outlook 2016

通过执行一个或多个任务来响应通知。执行的任务取决于事件的类型和生成通知的对象。

ULONG OnNotify(
  ULONG cNotif,
  LPNOTIFICATION lpNotifications
);

参数

cNotif

[in]lpNotifications 参数指向的 NOTIFICATION 结构的计数。

lpNotifications

[in]指向一个或多个 NOTIFICATION 结构的指针，这些结构提供有关已发生的事件的信息。

返回值

S_OK

已成功处理通知。

备注

当客户端或 MAPI 调用服务提供商的 Advise 方法以注册以接收特定对象的特定类型的通知时，通知过程将启动。建议方法的参数之一是指向实现 IMAPIAdviseSink 接口的建议接收器对象的指针。当与已注册通知对应的目标对象发生事件时，服务提供商直接或间接通过 MAPI 调用建议接收器的 OnNotify 方法。

对 OnNotify 的 调用可以在导致事件的 MAPI 调用期间发生，也可以在以后的某个时间发生。在支持多个执行线程的系统上，可以在用于注册的同一线程上或在不同的线程上调用 OnNotify 。客户端可以通过使用 HrThisThreadAdviseSink 函数创建传递给 Advise 的建议接收器，确保对用于调用 Advise 的同一线程进行 OnNotify 调用。

lpNotifications 参数指向一个或多个 NOTIFICATION 结构，这些结构描述事件期间发生更改的内容。每种类型的事件都有不同类型的 NOTIFICATION 结构。

下表列出了用于表示可能的事件类型的值以及与每个值关联的结构：

通知事件类型	相应的结构
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

有关如何设置和停止通知的详细信息，请参阅以下任何接口的 “建议 ”和 “取消advise ”方法的参考条目： IABLogon、 IAddrBook、 IMAPIForm、 IMAPISession、 IMAPITable、 IMsgStore 和 IMSLogon。

有关通知过程的常规信息，请参阅 MAPI 中的事件通知。

针对实现者的说明

OnNotify 实现通常由预期收到的每种类型的通知的一个或多个代码块组成。在这些代码块中，执行你认为必要的任何任务作为对通知的响应。例如，假设注册以在对话框显示中包含的文件夹上接收 fnevObjectModified 通知。在用于处理 fnevObjectModified 通知的 OnNotify 方法中包含的代码块中，你可能会向对话框发送 Windows 消息以请求更新显示。

请勿修改或释放传递给 OnNotify 的 NOTIFICATION 结构。结构中的数据仅在 OnNotify 返回之前有效。

给调用方的说明

当多个对象发生更改时，可以在对 OnNotify 的单个调用或多个调用中通知已注册的建议接收器，具体取决于内存约束。无论更改是一个方法调用还是多个方法调用的结果，都是如此。例如，调用 IMAPIFolder：：CopyMessages 可能会影响多个邮件和文件夹。作为邮件存储提供程序，可以使用目标文件夹的 fnevObjectModified 事件类型对 OnNotify 进行一次调用，或者针对每个影响邮件调用一次。同样，如果客户端对 IMAPIFolder：：CreateMessage 进行重复调用，这些调用可以合并到文件夹的一个 fnevObjectModified 事件中，也可以为每个新邮件分隔为单独的 fnevObjectCreated 事件。

有关如何以及何时生成通知的详细信息，请参阅 MAPI 中的事件通知和支持事件通知。