IABLogon::Advise
适用于：Outlook 2013 | Outlook 2016
注册调用方以接收影响容器、消息用户或通讯组列表的指定事件的通知。
HRESULT Advise(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG FAR * lpulConnection
);
参数
cbEntryID
[in] lpEntryID 参数指向的条目标识符中的字节计数。
lpEntryID
[in]指向应生成通知的对象条目标识符的指针。
ulEventMask
[in]值的位掩码，指示调用方感兴趣的通知事件类型，并且应包含在注册中。 有一个相应的 NOTIFICATION 结构与每种类型的事件相关联，用于保存有关该事件的信息。 下表列出了 ulEventMask 参数的有效值以及与每个值关联的结构。
| 通知事件类型 | 相应的 NOTIFICATION 结构 |
|---|---|
|
fnevCriticalError |
ERROR_NOTIFICATION |
|
fnevObjectCreated |
OBJECT_NOTIFICATION |
|
fnevObjectDeleted |
OBJECT_NOTIFICATION |
|
fnevObjectModified |
OBJECT_NOTIFICATION |
|
fnevObjectCopied |
OBJECT_NOTIFICATION |
|
fnevObjectMoved |
OBJECT_NOTIFICATION |
lpAdviseSink
[in]指向建议接收器对象的指针，用于接收后续通知。
lpulConnection
[out]指向表示通知注册的非零值的指针。
返回值
S_OK
通知注册成功。
MAPI_E_INVALID_ENTRYID
在 lpEntryID 参数中传递的条目标识符的格式不合适。
MAPI_E_NO_SUPPORT
通讯簿提供程序不支持通知，可能是因为它不允许对其对象进行更改。
MAPI_E_UNKNOWN_ENTRYID
通讯簿提供程序无法处理 在 lpEntryID 中传递的条目标识符。
备注
通讯簿提供程序实现 IABLogon：：Advise 方法，以注册调用方，使其在其其中一个容器中的对象发生更改时收到通知。 调用方可以注册有关消息传送用户、通讯组列表或整个容器的通知。
客户端通常调用 IAddrBook：：Advise 方法来注册通讯簿通知。 然后，MAPI 调用通讯簿提供程序的 Advise 方法，该提供程序负责 由 lpEntryID 中的条目标识符表示的对象。
当更改 ulEventMask 中表示的类型的指示对象时，将调用 lpAdviseSink 指向的建议接收器的 OnNotify 方法。 在 NOTIFICATION 结构中传递给 OnNotify 例程的数据描述该事件。
针对实现者的说明
无论是否通过 MAPI 的帮助，都可以支持通知。 MAPI 有三种支持对象方法可帮助服务提供商实现通知：
如果选择使用 MAPI 支持方法，请在调用 Advise 方法时调用 Subscribe 并释放 lpAdviseSink 指针。
如果选择自行支持通知，请调用 lpAdviseSink 参数表示的建议接收器的 AddRef 方法，以保留此指针的副本。 保留此副本，直到调用 IABLogon：：Unadvise 方法以取消注册。
无论支持通知的方式如何，都向通知注册分配一个非零连接号，并在 lpulConnection 参数中返回它。 在调用 Unadvise 方法之前，请勿释放此连接号。
给调用方的说明
在 lpAdviseSink 参数中传递给 Advise 的建议接收器指针可以指向已创建的对象，或者 MAPI 已通过 HrThisThreadAdviseSink 函数创建的对象。 如果支持多个执行线程，并希望确保对 OnNotify 方法的后续调用在适当的线程上发生，则可能需要使用 HrThisThreadAdviseSink。
准备好在调用建议后和调用 Unadvise 之前随时释放建议接收器对象。 因此，你应该在 建议 返回后释放建议接收器对象，除非你有特定的长期用途。
有关通知过程的详细信息，请参阅 MAPI 中的事件通知。 有关如何使用 IMAPISupport 方法支持通知的信息，请参阅 支持事件通知。 有关多线程处理和 MAPI 的详细信息，请参阅 MAPI 中的线程处理。