IMAPIForm::Advise

The IMAPIForm::Advise method registers a form viewer for notifications about changes to a form.

Quick Info

See IMAPIForm : IUnknown1MIPF86.

HRESULT Advise(

Parameters

pAdvise

[in] Pointer to the view advise sink object to be called when an event occurs for the form object about which notification has been requested.

pulConnection

[out] Pointer to a variable that upon a successful return holds the connection number for the notification registration. The connection number must be nonzero.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form viewers call the IMAPIForm::Advise method to register for notification callbacks when changes occur to a form. A form server s implementation of Advise keeps a copy of the pointer to the view advise sink object passed in the pAdvise parameter and uses this pointer in its notification callbacks. The Advise implementation should call the IUnknown::AddRef method on the view advise sink object to retain this pointer to the advise sink until notification registration is canceled. The Advise implementation should also assign a nonzero connection number to the notification registration and call AddRef on this number before returning it in the pulConnection parameter.

To cancel a notification registration, a form viewer calls the IMAPIForm::Unadvise1DS4_Z0 method. During the call to Unadvise, or shortly thereafter, the saved pointer to the view advise sink object is released.

For more information on the notification process, see Event Notification in MAPIE.8REW.

See Also