IAddrBook::Advise

The IAddrBook::Advise method registers a client or service provider to receive notifications about changes to one or more entries in the address book.

Quick Info

See IAddrBook : IMAPIProp.

HRESULT Advise(
  ULONG cbEntryID,                 
  LPENTRYID lpEntryID,             
  ULONG ulEventMask,               
  LPMAPIADVISESINK lpAdviseSink,   
  ULONG FAR * lpulConnection       
);

Parameters

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier of the address book container, messaging user, or distribution list that will generate a notification when a change occurs of the type or types described in the ulEventMask parameter.

ulEventMask

[in] One or more notification events that the caller is registering to receive. Each event is associated with a particular notification structure containing information about the change that occurred. The following table lists the valid values for ulEventMask and their corresponding structures.

Notification event	Corresponding structure
`fnevCriticalError`	ERROR_NOTIFICATION
`fnevObjectCreated`	OBJECT_NOTIFICATION
`fnevObjectDeleted`	OBJECT_NOTIFICATION
`fnevObjectModified`	OBJECT_NOTIFICATION
`fnevObjectCopied`	OBJECT_NOTIFICATION
`fnevObjectMoved`	OBJECT_NOTIFICATION
`fnevTableModified`	TABLE_NOTIFICATION

lpAdviseSink

[in] Pointer to the advise sink object to be called when the event for which notification has been requested occurs.

lpulConnection

[out] Pointer to a nonzero connection number that represents the notification registration.

Return Values

S_OK: The notification registration was successful.
MAPI_E_INVALID_ENTRYID: The address book provider responsible for the entry identifier passed in lpEntryID could not register a notification for the corresponding entry.
MAPI_E_NO_SUPPORT: Notification is not supported by the address book provider responsible for the object identified by the entry identifier passed in the lpEntryID parameter.
MAPI_E_UNKNOWN_ENTRYID: The entry identifier passed in lpEntryID cannot be handled by any of the address book providers in the profile.

Remarks

Clients and service providers call the IAddrBook::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 lpEventMask parameter.

MAPI forwards this Advise call to the address book provider 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 some 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 Unadvise call to cancel the notification, clients should release their advise sink objects when Advise returns.

For more information on the notification process, see Event Notification in MAPI.