| title | description | manager | ms.date | ms.audience | ms.topic | ms.service | ms.localizationpriority | api_name | api_type | ms.assetid | ||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
IABLogonAdvise |
This article describes the IABLogonAdvise function and provides syntax, parameters, and return value. |
lindalu |
03/09/2015 |
Developer |
reference |
office-online-server |
medium |
|
|
375d65b1-607d-4e2a-8052-9bcbf08fc2ac |
Applies to: Outlook 2013 | Outlook 2016
Registers the caller to receive notification of specified events that affect a container, messaging user, or distribution list.
HRESULT Advise(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG FAR * lpulConnection
);cbEntryID
[in] The count of bytes in the entry identifier pointed to by the lpEntryID parameter.
lpEntryID
[in] A pointer to the entry identifier of the object about which notifications should be generated.
ulEventMask
[in] A bitmask of values that indicate the types of notification events that the caller is interested in and should be included in the registration. There is a corresponding NOTIFICATION structure associated with each type of event that holds information about the event. The following table lists the valid values for the ulEventMask parameter and the structures associated with each value.
| Notification event type | Corresponding NOTIFICATION structure |
|---|---|
| fnevCriticalError |
ERROR_NOTIFICATION |
| fnevObjectCreated |
OBJECT_NOTIFICATION |
| fnevObjectDeleted |
OBJECT_NOTIFICATION |
| fnevObjectModified |
OBJECT_NOTIFICATION |
| fnevObjectCopied |
OBJECT_NOTIFICATION |
| fnevObjectMoved |
OBJECT_NOTIFICATION |
lpAdviseSink
[in] A pointer to an advise sink object to receive the subsequent notifications.
lpulConnection
[out] A pointer to a nonzero value that represents the notification registration.
S_OK
The notification registration was successful.
MAPI_E_INVALID_ENTRYID
The entry identifier passed in the lpEntryID parameter is not in the appropriate format.
MAPI_E_NO_SUPPORT
The address book provider does not support notification, possibly because it does not allow changes to be made to its objects.
MAPI_E_UNKNOWN_ENTRYID
The address book provider cannot handle the entry identifier passed in lpEntryID.
Address book providers implement the IABLogon::Advise method to register the caller to be notified when a change occurs to an object in one of their containers. Callers can register for notifications regarding messaging users, distribution lists, or entire containers.
Clients typically call the IAddrBook::Advise method to register for address book notifications. MAPI then calls the Advise method of the address book provider that is responsible for the object represented by the entry identifier in lpEntryID.
When a change occurs to the indicated object of the type represented in ulEventMask, a call is made to the OnNotify method of the advise sink pointed to by lpAdviseSink. Data passed in the NOTIFICATION structure to the OnNotify routine describes the event.
You can support notification with or without help from MAPI. MAPI has three support object methods to help service providers implement notification:
If you elect to use the MAPI support methods, call Subscribe when your Advise method is called and release the lpAdviseSink pointer.
If you elect to support notification yourself, call the AddRef method of the advise sink represented by the lpAdviseSink parameter to keep a copy of this pointer. Maintain this copy until your IABLogon::Unadvise method is called to cancel the registration.
Regardless of how you support notification, assign a nonzero connection number to the notification registration and return it in the lpulConnection parameter. Do not release this connection number until the Unadvise method has been called.
The advise sink pointer that you pass in the lpAdviseSink parameter to Advise can point to an object that you have created or that MAPI has created through the HrThisThreadAdviseSink function. You might want to use HrThisThreadAdviseSink if you support multiple threads of execution and want to be sure that that subsequent calls to your OnNotify method occur at an appropriate time on an appropriate thread.
Be prepared for your advise sink object to be released any time after your call to Advise and before your call to Unadvise. Therefore, you should release your advise sink object after Advise returns, unless you have a specific long-term use for it.
For more information about the notification process, see Event Notification in MAPI. For information about how to use the IMAPISupport methods to support notification, see Supporting Event Notification. For more information about multithreading and MAPI, see Threading in MAPI.