HrAllocAdviseSink

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

Note  This function may not be supported in future versions of MAPI.

Quick Info

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.

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.

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

See Also

Notification Functions