Last modified: July 23, 2011
Applies to: Outlook
Registers a client or service provider to receive notifications about changes to one or more entries in the address book.
Clients and service providers call the Advise method to register for a particular type or types of notification on an address book entry. The types of notification are indicated by the event mask passed in with the ulEventMask parameter.
MAPI forwards this Advise call to the address book provider that is responsible for the entry as indicated by the entry identifier in the lpEntryID parameter. The address book provider either handles the registration itself or calls the support method, IMAPISupport::Subscribe, to prompt MAPI to register the caller. A nonzero connection number is returned to represent the successful registration.
Whenever a change occurs to the entry of the type indicated by the notification registration, the address book provider calls the IMAPIAdviseSink::OnNotify method for the advise sink object specified in the lpAdviseSink parameter. The OnNotify method includes a NOTIFICATION structure as an input parameter that contains data to describe the event.
Depending on the address book provider, the call to OnNotify can occur immediately following the change to the registered object or at a later time. On systems that support multiple threads of execution, the call to OnNotify can occur on any thread. Clients can request that these notifications occur on a particular thread by calling the HrThisThreadAdviseSink function to create the advise sink object that is passed to Advise.
Because an address book provider can release the advise sink object passed in by clients at any time after the successful completion of the Advise call and before an IAddrBook::Unadvise call to cancel the notification, clients should release their advise sink objects when Advise returns.
For more information about the notification process, see Event Notification in MAPI.