IMSLogon::Advise

The IMSLogon::Advise method registers a object with a message store provider for notifications about changes within the message store. The message store will then send notifications about changes to the registered object.

Quick Info

See IMSLogon : IUnknown.

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

Parameters

cbEntryID

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

lpEntryID

[in] Pointer to the entry identifier of the object about which notifications should be generated. This object can be a folder, a message, or any other object in the message store. Alternatively, if MAPI sets the cbEntryID parameter to zero and passes NULL for lpEntryID, the advise sink provides notifications about changes to the entire message store.

ulEventMask

[in] Event mask of the types of notification events occurring for the object about which MAPI will generate notifications. The mask filters specific cases. Each event type has a structure associated with it that holds additional information about the event. The following table lists the possible event types along with their corresponding structures.

Notification event type	Corresponding structure
fnevCriticalError	ERROR_NOTIFICATION
fnevNewMail	NEWMAIL_NOTIFICATION
fnevObjectCreated	OBJECT_NOTIFICATION
fnevObjectDeleted	OBJECT_NOTIFICATION
fnevObjectModified	OBJECT_NOTIFICATION
fnevObjectCopied	OBJECT_NOTIFICATION
fnevObjectMoved	OBJECT_NOTIFICATION
fnevSearchComplete	OBJECT_NOTIFICATION
fnevStatusObjectModified	STATUS_OBJECT_NOTIFICATION

lpAdviseSink

[in] Pointer to an advise sink object to be called when an event occurs for the session object about which notification has been requested. This advise sink object must already exist.

lpulConnection

[out] Pointer to a variable that upon a successful return holds the connection number for the notification registration. The connection number must be nonzero.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NO_SUPPORT

The operation is not supported by MAPI or by one or more service providers.

Remarks

Message store providers implement the IMSLogon::Advise method to register an object for notification callbacks. Whenever a change occurs to the indicated 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 client application should use the HrThisThreadAdviseSink function.

To provide notifications, the message store 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 IMSLogon::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, providers must be prepared for the advise sink object to be released. A provider should therefore release its advise sink object after Advise returns unless it has a specific long-term use for it.

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

See Also

HrThisThreadAdviseSink, IMAPIAdviseSink::OnNotify, IMSLogon::Unadvise, NOTIFICATION