HrAllocAdviseSink

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.

Creates an advise sink object, given a context specified by the calling implementation and a callback function to be triggered by an event notification.

STDAPI HrAllocAdviseSink(
  LPNOTIFCALLBACK lpfnCallback,
  LPVOID lpvContext,
  LPMAPIADVISESINK FAR * lppAdviseSink
);

Parameters

• lpfnCallback
  [in] Pointer to a callback function based on the NOTIFCALLBACK prototype that MAPI is to call when a notification event occurs for the newly created advise sink.

• lpvContext
  [in] Pointer to caller data passed to the callback function when MAPI calls it. The caller data can represent an address of significance to the client or provider. Typically, for C++ code, the lpvContext parameter represents a pointer to the address of an object.

• lppAdviseSink
  [out] Pointer to a pointer to an advise sink object.

Return Value

None.

Remarks

To use the HrAllocAdviseSink function, a client application or service provider creates an object to receive notifications, creates a notification callback function based on the NOTIFCALLBACK function prototype that goes with that object, and passes a pointer to the object in the HrAllocAdviseSink function as the lpvContext value. Doing so performs a notification; and as part of the notification process, MAPI calls the callback function with the object pointer as the context.

MAPI implements its notification engine asynchronously. In C++, the notification callback can be an object method. If the object generating the notification is not present, the client or provider requesting notification must keep a separate reference count for that object for the object's advise sink.

Caution
HrAllocAdviseSink should be used sparingly; it is safer for clients to create their own advise sinks.