IMAPISupport::Subscribe

  • Article

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 page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Registers an advise sink to receive notifications through MAPI.

HRESULT Subscribe(
LPNOTIFKEY lpKey,
ULONG ulEventMask,
ULONG ulFlags,
LPMAPIADVISESINK lpAdviseSink,
ULONG FAR * lpulConnection
);

Parameters

  • lpKey
    [in] A pointer to a notification key that represents the advise source object. The lpKey parameter cannot be NULL.

  • ulEventMask
    [in] A mask of values that indicate the types of notification events that the caller is interested in and should be included in the registration. The following values are valid:

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

    • fnevExtended
      Registers for notifications about events specific to the particular address book or message store provider.

    • 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.

  • ulFlags
    [in] A bitmask of flags that controls how notification occurs. The following flag can be set:

    • NOTIFY_SYNC
      When the caller calls the IMAPISupport::Notify method to generate notifications for this advise sink, Notify should make all necessary calls to advise sinks before returning. If this flag is not set, notification is asynchronous and callbacks are queued to the processes that have subscribed and started when those processes gain control of the CPU.

  • lpAdviseSink
    [in] A pointer to an advise sink object.

  • lpulConnection
    [out] A pointer to a nonzero connection number that represents the registration.

Return Value

  • S_OK
    The notification registration was successful.

Remarks

The IMAPISupport::Subscribe method is implemented for all service provider support objects. Service providers call Subscribe from one of their Advise methods to allow MAPI to manage the notifications.

Notes to Callers

To use the MAPI support methods for notification, create a key for the advise source the object about which notifications should be generated. The value of the key must be unique and should be easily regenerated each time the object changes.

MAPI uses the notification key to search for any callback functions registered through the HrAllocAdviseSink function for the corresponding advise source. Pass this key to IMAPISupport::Notify whenever you need to generate a notification for the corresponding advise source.

The NOTIFY_SYNC flag affects the operation of subsequent calls to Notify. When you set NOTIFY_SYNC, Notify does not return until it has finished sending all of the necessary notifications. When you do not set NOTIFY_SYNC, Notify operates asynchronously, possibly returning before all of the notifications have been sent.

See Also

Reference

HrAllocAdviseSink

IMAPIAdviseSink::OnNotify

IMAPISupport::Notify

NOTIFICATION

NOTIFKEY

IMAPISupport : IUnknown