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
|
Header file:
|
MAPIUTIL.H |
|
Implemented
by: |
MAPI |
|
Called by: |
Client
applications and service providers |
STDAPI HrAllocAdviseSink(
|
LPNOTIFCALLBACK lpfnCallback, |
|
|
LPVOID lpvContext,
|
|
|
LPMAPIADVISESINK FAR * lppAdviseSink |
|
|
); |
|
Parameters
lpfnCallback
[in] Pointer
to the callback function defined by a client application or service provider
that MAPI is to call when a notification event occurs for the newly created
advise sink.
lpvContext
[in] Pointer
to an arbitrary value passed to the callback function when MAPI calls it. This
value 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 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.