IDataObject：:D Advise 方法 (objidl.h)

  • 项目

由支持建议接收器的对象调用，以在数据对象与建议接收器之间创建连接。 这使建议接收器能够收到对象数据更改的通知。

语法

HRESULT DAdvise(
  [in]  FORMATETC   *pformatetc,
  [in]  DWORD       advf,
  [in]  IAdviseSink *pAdvSink,
  [out] DWORD       *pdwConnection
);

参数

[in] pformatetc

指向 FORMATETC 结构的指针，该结构定义将用于将来通知的格式、目标设备、方面和媒体。 例如，仅当数据对象中数据的位图表示形式更改时，一个接收器可能才想要知道。 另一个接收器可能只对同一对象的图元文件格式感兴趣。 当相关数据发生更改时，每个建议接收器都会收到通知。 发生通知时，此数据将传回建议接收器。

[in] advf

一组用于控制咨询连接的标志。 可能的值来自 ADVF 枚举。 但是，只有一些可能的 ADVF 值与此方法相关。 下表简要介绍了相关值。

ADVF 值 说明
ADVF_NODATA 要求数据对象避免发送带有通知的数据。 通常发送数据。 此标志是替代默认行为的一种方法。 使用ADVF_NODATA时，传递给 OnDataChange 的 STGMEDIUM 结构的 tymed 成员通常包含TYMED_NULL。 然后，调用方可以使用后续 IDataObject：：GetData 调用检索数据。
ADVF_ONLYONCE 导致在发送第一个更改通知后销毁通知连接。 代表调用方对 IDataObject：:D Unadvise 进行隐式调用以删除连接。
ADVF_PRIMEFIRST 请求其他初始通知。 ADVF_ONLYONCE和ADVF_PRIMEFIRST的组合实际上提供了异步 IDataObject：：GetData 调用。
ADVF_DATAONSTOP 使用 ADVF_NODATA 指定时，此标志会导致在销毁数据对象之前发送包含数据的最后一个通知。

如果在不使用ADVF_NODATA的情况下使用，则可以通过以下方式之一实现 DAdvise ：

  • 可以忽略ADVF_DATAONSTOP。
  • 对象的行为就像指定了ADVF_NODATA一样。
更改通知仅在关闭的情况下发送。 关闭前的数据更改不会导致发送通知。

[in] pAdvSink

指向将接收更改通知的咨询接收器上的 IAdviseSink 接口的指针。

[out] pdwConnection

标识此连接的令牌。 稍后，可以通过将此令牌传递给 IDataObject：:D Unadvise) 来删除 (建议连接。 如果此值为 0，则表示未建立连接。

返回值

此方法在成功时返回S_OK。 其他可能的值包括以下内容。

返回代码 说明
E_NOTIMPL
 此方法未在数据对象上实现。
DV_E_LINDEX
 lindex 的值无效;目前仅支持 -1。
DV_E_FORMATETC
 pformatetc 的值无效。
OLE_E_ADVISENOTSUPPORTED
 该数据对象不支持更改通知。

注解

DAdvise 在数据对象和调用方之间创建更改通知连接。 调用方提供一个通知接收器，当对象的数据发生更改时，通知可以发送到该接收器。

仅用于数据传输的对象通常不支持咨询通知，并且从 DAdvise 返回OLE_E_ADVISENOTSUPPORTED。

给调用方的说明

支持建议接收器的对象调用 DAdvise 来设置连接，指定传入的 FORMATETC 结构中感兴趣的格式、方面、介质和/或目标设备。 如果数据对象根本不支持一个或多个请求的属性或发送通知，则它可以通过返回OLE_E_ADVISENOTSUPPORTED来拒绝连接。

链接对象的容器可以直接与绑定链接源或间接通过管理连接的标准 OLE 链接对象设置咨询连接。 使用绑定链接源设置Connections不会自动删除。 容器必须在绑定链接源上显式调用 IDataObject：:D Unadvise 以删除咨询连接。 通过 IOleLink 接口操作的 OLE 链接对象在默认处理程序中实现。 删除链接对象时，通过 OLE 链接对象设置的Connections将被销毁。

OLE 默认链接对象使用链接源创建“通配符建议”，以便 OLE 可以保留上次更改的时间。 此建议专门用于记录任何内容更改的时间。 OLE 会忽略可能已更改的所有数据格式，仅注意到上次更改的时间。 若要允许通配符建议，请在调用 DAdvise 之前按如下所示设置 FORMATETC 成员：

cf == 0; 
ptd == NULL; 
dwAspect == -1; 
lindex == -1 
tymed == -1;

建议标志还应包括ADVF_NODATA。 应用程序应始终接受来自 OLE 的通配符建议。

实施者说明

为了简化 DAdvise 和 IDataObject (DUnadvise 和 EnumDAdvise) 中支持通知的其他通知方法的实现，OLE 提供了一个建议持有者对象，用于管理通知的注册和发送。 若要获取指向此对象的指针，请在首次调用 DAdvise 时调用帮助程序函数 CreateDataAdviseHolder。 这会提供指向对象的 IDataAdviseHolder 接口的指针。 然后，在数据建议持有者中委托 对 IDataAdviseHolder：：Advise 方法的调用，该方法创建并随后管理请求的连接。

要求

要求 值
最低受支持的客户端 Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
目标平台 Windows
标头 objidl.h

另请参阅

CreateDataAdviseHolder

IAdviseSink：：OnDataChange

IDataObject