IDataAdviseHolder::Advise
Creates a
connection between an advise sink and a data object for receiving notifications.
HRESULT Advise(
|
IDataObject
* pDataObject, |
//Pointer to the data object for which notifications
are requested |
|
FORMATETC
* pFormatetc, |
//Pointer to the description of data to the advise
sink |
|
DWORD advf, |
//Flags that specify how the notification takes
place |
|
IAdviseSink * pAdvSink, |
//Pointer to the advise sink requesting notification |
|
DWORD * pdwConnection |
//Pointer to the connection token |
|
); |
|
Parameters
pDataObject
[in] Pointer
to the IDataObject interface on the data object for which notifications
are requested. If data in this object changes, a notification is sent to the
advise sinks that have requested notification.
pFormatetc
[in] Pointer
to the specified format, medium, and target device that is of interest to the advise
sink requesting notification. For example, one sink may want to know only when
the bitmap representation of the data in the data object changes. Another sink
may be interested in only the metafile format of the same object. Each advise
sink is notified when the data of interest changes. This data is passed back to
the advise sink when notification occurs.
advf
[in] Contains
a group of flags for controlling the advisory connection. Valid values are from
the enumeration ADVF.
However, only some of the possible ADVF values are relevant for this
method. The following table briefly describes the relevant values; a more
detailed description can be found in the description of the ADVF
enumeration.
|
ADVF
Value |
Description |
|
ADVF_NODATA |
Asks that
no data be sent along with the notification. |
|
ADVF_ONLYONCE |
Causes the
advisory connection to be destroyed after the first notification is sent. An
implicit call to IDataAdviseHolder::Unadvise17J8O56 is made on behalf of the caller to
remove the connection. |
|
ADVF_PRIMEFIRST |
Causes an
initial notification to be sent regardless of whether or not data has changed
from its current state. |
|
ADVF_DATAONSTOP |
When
specified with ADVF_NODATA, this flag causes a last notification with the
data included to be sent before the data object is destroyed. When
ADVF_NODATA is not specified, this flag has no effect. |
pAdvSink
[in] Pointer
to the IAdviseSink interface on the advisory sink that receives the
change notification.
pdwConnection
[out] Pointer
to a DWORD token that identifies this connection. The calling object can later
delete the advisory connection by passing this token to IDataAdviseHolder::Unadvise. If this value is zero,
the connection was not established.
Return Values
This method
supports the standard return value E_INVALIDARG, as well as the following:
S_OK
The advisory
connection was created.
Remarks
Through the
connection established through this method, the advisory sink can receive
future notifications in a call to IAdviseSink::OnDataChange.
An object
issues a call to IDataObject::DAdvise to request notification on changes to the
format, medium, or target device of interest. This data is specified in the pFormatetc
parameter. The DAdvise method is usually implemented to call IDataAdviseHolder::Advise
to delegate the task of setting up and tracking a connection to the advise
holder. When the format, medium, or target device in question changes, the data
object calls IDataAdviseHolder::SendOnDataChange to send the necessary
notifications.
The
established connection can be deleted by passing the value in pdwConnection
in a call to IDataAdviseHolder::Unadvise.
See also
ADVF, CreateDataAdviseHolder, FORMATETC, IDataAdviseHolder::Unadvise, IDataObject::DAdvise