IMAPISession::Advise

Applies to: Office 2010 | Outlook 2010 | Visual Studio

Registers to receive notification of specified events that affect the session.

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

Parameters

• cbEntryID
  [in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

• lpEntryID
  [in] A pointer to the entry identifier of the address book or message store object about which notifications should be generated, or NULL, which indicates that the client is registering to receive notifications about events that affect only the session.

• ulEventMask
  [in] A mask of values that indicate the types of notification events that the client is interested in and should be included in the registration. If lpEntryID is NULL, MAPI automatically registers the client for critical error events that affect only the session. When lpEntryID points to an entry identifier, the following values are valid for the ulEventMask parameter:

  • fnevCriticalError
    Registers for notifications about severe errors, such as insufficient memory.

  • fnevExtended
    Registers for notifications about events specific to a particular address book or message store provider and about session shut down.

  • fnevNewMail
    Registers for notifications about the arrival of new messages.

  • fnevObjectCreated
    Registers for notifications about the creation of a new object.

  • fnevObjectCopied
    Registers for notifications about an object being copied.

  • fnevObjectDeleted
    Registers for notifications about an object being deleted.

  • fnevObjectModified
    Registers for notifications about an object being modified.

  • fnevObjectMoved
    Registers for notifications about an object being moved.

  • fnevSearchComplete
    Registers for notifications about the completion of a search operation.

• lpAdviseSink
  [in] A pointer to an advise sink object to receive the subsequent notifications. This advise sink object must have already been allocated.

• lpulConnection
  [out] A pointer to a nonzero number that represents the connection between the caller's advise sink object and the session.

Return Value

• S_OK
  The registration was successful.

• MAPI_E_INVALID_ENTRYID
  The entry identifier pointed to by lpEntryID does not represent a valid entry identifier.

• MAPI_E_NO_SUPPORT
  The service provider responsible for the entry identifier pointed to by lpEntryID either does not support the type of events specified in the ulEventMask parameter or does not support notification.

• MAPI_E_UNKNOWN_ENTRYID
  The entry identifier pointed to by lpEntryID cannot be handled by any of the service providers in the profile.

Remarks

The IMAPISession::Advise method establishes a connection between the caller's advise sink object, the session and, optionally, a service provider. This connection is used to send notifications to the advise sink when one or more events specified in the ulEventMask parameter occur to the object pointed to by lpEntryID. When lpEntryID is NULL, the target object is the session and notifications are sent only for critical errors and extended events.

When lpEntryID points to a valid entry identifier, MAPI calls the Advise method of the logon object that belongs to the responsible service provider. For example, if lpEntryID points to the entry identifier of a distribution list, MAPI calls the appropriate address book provider's IABLogon::Advise method.

To send a notification, either the service provider or MAPI calls the registered advise sink's IMAPIAdviseSink::OnNotify method. One of the parameters to OnNotify, a notification structure, contains information that describes the specific event.

Notes to Callers

On systems that support multiple threads of execution, the call to OnNotify can also occur on any thread at any time. If you need assurance that notifications will occur only at a particular time on a particular thread, call the HrThisThreadAdviseSink function to generate the advise sink object that you pass to the Advise method.

To determine when a client has logged off, register for notifications in your service provider by calling Advise with lpEntryID set to NULL and cbEntryID set to 0. When the logoff occurs, you will receive an fnevExtended notification.

After a call to Advise has succeeded and before IMAPISession::Unadvise has been called to cancel the registration, release your advise sink object unless you have a specific long-term use for it.

For an overview of the notification process, see Event Notification in MAPI.

For more information about handling notifications, see Handling Notifications.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

See Also

Reference

IABLogon::Advise

HrThisThreadAdviseSink

IMAPIAdviseSink::OnNotify

IMAPISession::Unadvise

IMAPISession : IUnknown

Concepts

MFCMAPI as a Code Sample

Event Notification in MAPI