Creates a connection between a data object and an advise sink so the advise
sink can receive notifications of changes in the data object.
| FORMATETC * pFormatetc,
||//Description of data that is of interest to the advise sink
| DWORD advf,
||//Flags that specify how the notification takes place
| IAdviseSink * pAdvSink,
||//The advise sink that is requesting notification
| DWORD * pdwConnection
||//Identifies the connection for future calls to the Unadvise method
[in]Points to the particular format, target device, aspect, and medium that
will be used for future notifications. For example, one sink may want to know
only when the bitmap representation of the data in the 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.
[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. You can find a more detailed description in ADVF
||Asks the data object to avoid sending data with the notifications. Typically
data is sent. This flag is a way to override the default behavior. When
ADVF_NODATA is used, the TYMED member of the STGMEDIUM structure that is passed to OnDataChange will usually contain TYMED_NULL. The
caller can then retrieve the data with a subsequent IDataObject::GetData call.
||Causes the advisory connection to be destroyed after the first change
notification is sent. An implicit call to IDataObject::DUnadvise is made on behalf of the caller to remove the connection.
||Asks for an additional initial notification. The combination of ADVF_ONLYONCE
and ADVF_PRIMEFIRST provides, in effect, an asynchronous IDataObject::GetData call.
||When specified with ADVF_NODATA, this flag causes a last notification with the
data included to to be sent before the data object is destroyed.
If used without ADVF_NODATA, IDataObject::DAdvise can be implemented in one of the following ways:
- the ADVF_DATAONSTOP can be ignored.
- the object can behave as if ADVF_NODATA was specified.
- a change notification is sent only in the shutdown case. Data changes prior
to shutdown do not cause a notification to be sent.
[in]Points to the advisory sink that will receive the change notification.
[in]Points to the location of a returned token that identifies this
connection. You can use this token later to delete the advisory connection (by passing it
). If this value is zero, the connection was not established.
The advisory connection was created.
One or more arguments are invalid.
An unexpected error occurred.
The connection was not created because the system ran out of memory.
This method is not implemented for the data object.
Invalid value for lindex
; currently, only -1 is supported.
Invalid value for pFormatetc
The data object does not support change notification.
method creates a connection between the data object and the caller. The
caller provides an advisory sink through which the notifications can be sent when
the object's data changes. The advise sink issues the call to IDataObject::DAdvise
. Advisory connections are associated with a particular description of the
data. Data clients specify the format, aspect, medium, and/or target device of
interest in the FORMATETC
structure passed in. If the data object does not support one or more of the
requested attributes or the sending of notifications at all. It can refuse the
connection by returning OLE_E_ADVISENOTSUPPORTED.
Objects used for data transfer typically do not support advisory notifications
and return OLE_E_ADVISENOTSUPPORTED from IDataObject::DAdvise
Containers of linked objects can set up advisory connections directly with the
bound link source or indirectly via the standard OLE link object that manages
the connection. Connections set up with the bound link source are not
automatically deleted. The container must explicitly call IDataObject::DUnAdvise
on the bound link source to delete it. Connections set up through the OLE
link object are destroyed when the link object is deleted.
The OLE default link object creates a "wildcard advise" with the link source
so OLE can maintain the time of last change. This advise is specifically used to
note the time that anything changed. OLE ignores all data formats that may
have changed, noting only the time of last change. To allow wildcard advises, set
members as follows before calling IDataObject::DAdvise
cf == 0;
ptd == NULL;
lindex == -1
tymed == -1;
The advise flags should also include ADVF_NODATA. Wildcard advises from OLE
should always be accepted by applications.
For those data objects that support notifications, a data advise holder object
can be used to simplify the implementation of DAdvise
and the other notification methods in IDataObject
). The data advise holder is an object provided by OLE that manages the
registration and sending of notifications. With the first invocation of DAdvise
, the helper function CreateDataAdviseHolder
can be called to create the data advise holder and provide the data object
with a pointer to it. The data object then delegates to the IDataAdviseHolder::Advise
method in the data advise holder to create the requested connection.
, IAdviseSink::OnDataChange, IDataObject::DUnAdvise
- Software for developers
Software for Android Developers
- More information resources
Unix Manual Pages