Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
4/8/2010

The Advisemethod registers to receive notification of specified events affecting the message store.

Syntax 

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

Parameters

cbEntryID

[in] Must be 0.

lpEntryID

[in] Must be NULL.

ulEventMask

[in] A mask of values indicating the types of notification events that the client is interested in and should be included in the registration. See Remarksfor valid flags that can be combined for this parameter.

lpAdviseSink

[in] Reference to an advise sink object, implemented on IMAPIAdviseSink, to receive the subsequent notifications. This advise sink object must have already been allocated; it cannot be NULL.

lpulConnection

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

Return Value

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK

Indicates success.

MAPI_E_NO_SUPPORT

The message store provider does not support registration for notification through the message store.

Remarks

Adviseestablishes a connection between the caller's advise sink object and either the message store or an object in the message store. This connection is used to send notifications to the advise sink when one or more events, as specified in the ulEventMaskparameter, occur to the advise source object.

The ulEventMaskparameter is a bitmask composed of one or more of the flags described in the following table.

Flag Value Description

fnevObjectCopied

0x00000040

Registers for notifications about an object being copied.

fnevObjectCreated

0x00000004

Registers for notifications about the creation of a new object.

fnevObjectDeleted

0x00000008

Registers for notifications about an object being deleted.

fnevObjectModified

0x00000010

Registers for notifications about an object being modified.

fnevObjectMoved

0x00000020

Registers for notifications about an object being moved.

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

After a call to Advisehas succeeded and before IMsgStore::Unadvisehas been called to cancel the registration, be prepared for the advise sink object to be released. You should release your advise sink object after Advisereturns unless you have a specific long-term use for it.

Requirements

Header mapidefs.h
Library cemapi.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Pocket PC 2002 and later, Smartphone 2002 and later

See Also