IMAPITable::Advise

The IMAPITable::Advise method registers to receive notification of specified events affecting the table.

Quick Info

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

Parameters

ulEventMask: [in] Value indicating the type of event that will generate the notification. Only the following value is valid:

fnevTableModified

lpAdviseSink: [in] Pointer to an advise sink object to receive the subsequent notifications. This advise sink object must have been already allocated.
lpulConnection: [out] Pointer to a nonzero value that represents the successful notification registration.

Return Values

S_OK: The notification registration successfully completed.
MAPI_E_NO_SUPPORT: The table implementation either does not support changes to its rows and columns or does not support notification.

Remarks

Use the IMAPITable::Advise method to register a table object implemented in the provider for notification callbacks. Whenever a change occurs to the table object, the provider checks to see what event mask bit was set in the ulEventMask parameter and thus what type of change occurred. If a bit is set, then the provider calls the IMAPIAdviseSink::OnNotify method for the advise sink object indicated by the lpAdviseSink parameter to report the event. Data passed in the notification structure to the OnNotify routine describes the event.

The call to OnNotify can occur during the call that changes the object, or at any following time. On systems that support multiple threads of execution, the call to OnNotify can occur on any thread. For a way to turn a call to OnNotify that might happen at an inopportune time into one that is safer to handle, a provider should use the HrThisThreadAdviseSink function.

To provide notifications, the provider implementing Advise needs to keep a copy of the pointer to the lpAdviseSink advise sink object; to do so, it calls the IUnknown::AddRef method for the advise sink to maintain its object pointer until notification registration is canceled with a call to the IMAPITable::Unadvise method. The Advise implementation should assign a connection number to the notification registration and call AddRef on this connection number before returning it in the lpulConnection parameter. Service providers can release the advise sink object before the registration is canceled, but they must not release the connection number until Unadvise has been called.

After a call to Advise has succeeded and before Unadvise has been called, clients must be prepared for the advise sink object to be released. A client should therefore release its advise sink object after Advise returns unless it has a specific long-term use for it.

Because of the asynchronous behavior of notification, implementations that change table column settings can receive notifications with information organized in a previous column order. For instance, a table row might be returned for a message that has just been deleted from the container. Such a notification is sent when the column setting change has been made and information about it sent but the notification table view has not been updated with that information yet.

For more information on the notification process, see Event Notification in MAPI. For specific information about table notification, see About Table Notifications. For information about using the IMAPISupport methods to support notification, see Supporting Event Notification.