IAddrBook::Advise
适用于：Outlook 2013 | Outlook 2016
注册客户端或服务提供商，以接收有关通讯簿中一个或多个条目更改的通知。
HRESULT Advise(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG_PTR lpulConnection
);
参数
cbEntryID
[in] lpEntryID 参数指向的条目标识符中的字节计数。
lpEntryID
[in]指向通讯簿容器、消息用户或通讯组列表的入口标识符的指针，在 发生 ulEventMask 参数中描述的类型更改时将生成通知。
ulEventMask
[in]调用方注册要接收的一个或多个通知事件。 每个事件都与包含所发生更改相关信息的特定通知结构相关联。 下表列出了 ulEventMask 的有效值及其相应的结构。
| 通知事件 | 相应的结构 |
|---|---|
|
fnevCriticalError |
ERROR_NOTIFICATION |
|
fnevObjectCreated |
OBJECT_NOTIFICATION |
|
fnevObjectDeleted |
OBJECT_NOTIFICATION |
|
fnevObjectModified |
OBJECT_NOTIFICATION |
|
fnevObjectCopied |
OBJECT_NOTIFICATION |
|
fnevObjectMoved |
OBJECT_NOTIFICATION |
|
fnevTableModified |
TABLE_NOTIFICATION |
lpAdviseSink
[in]指向在请求通知的事件发生时要调用的建议接收器对象的指针。
lpulConnection
[out]指向表示通知注册的非零连接号的指针。
返回值
S_OK
通知注册成功。
MAPI_E_INVALID_ENTRYID
负责 在 lpEntryID 中传递的条目标识符的通讯簿提供程序无法为相应条目注册通知。
MAPI_E_NO_SUPPORT
通讯簿提供程序不支持通知，该地址簿提供程序负责由 lpEntryID 参数中传递的条目标识符标识的对象。
MAPI_E_UNKNOWN_ENTRYID
配置文件中的任何通讯簿提供程序都无法处理 lpEntryID 中传递的条目标识符。
备注
客户端和服务提供商调用 Advise 方法，以在通讯簿条目上注册特定类型或类型的通知。 通知的类型由使用 ulEventMask 参数传入的事件掩码指示。
MAPI 将此 建议 调用转发给通讯簿提供程序，该提供程序负责 lpEntryID 参数中的条目标识符指示的条目。 通讯簿提供程序可以自行处理注册，或者调用支持方法 IMAPISupport：：Subscribe，以提示 MAPI 注册调用方。 返回非零连接编号以表示注册成功。
每当更改通知注册所指示的类型条目时，通讯簿提供程序会为 lpAdviseSink 参数中指定的建议接收器对象调用 IMAPIAdviseSink：：OnNotify 方法。 OnNotify 方法包含 NOTIFICATION 结构作为输入参数，其中包含用于描述事件的数据。
根据通讯簿提供程序，对 OnNotify 的调用可以在对已注册的对象进行更改后立即发生，也可以在以后进行调用。 在支持多个执行线程的系统上，对 OnNotify 的调用可以在任何线程上发生。 客户端可以通过调用 HrThisThreadAdviseSink 函数来创建传递给 建议的建议接收器对象，请求在特定线程上发生这些通知。
由于通讯簿提供程序可以在成功完成 建议调用后 和 IAddrBook：：Unadvise 调用之前随时释放客户端传入的建议接收器对象以取消通知，因此客户端应在 建议 返回时释放其建议接收器对象。
有关通知过程的详细信息，请参阅 MAPI 中的事件通知。