Share via

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 值 Description
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。 其他可能的值包括下列專案。

傳回碼 Description
E_NOTIMPL
 沒有在資料物件上實作這個方法。
DV_E_LINDEX
 lindex 的值無效;目前僅支援 -1。
DV_E_FORMATETC
 pformatetc 的值無效。
OLE_E_ADVISENOTSUPPORTED
 資料物件不支援變更告知。

備註

DAdvise 會在數據物件與呼叫端之間建立變更通知連線。 呼叫端會提供通知接收，當對象的數據變更時，可以傳送通知。

直接用於數據傳輸的物件通常不支持諮詢通知，並從 DAdvise 傳回OLE_E_ADVISENOTSUPPORTED。

來電者附註

支持建議接收呼叫 DAdvise 的物件會呼叫 DAdvise 來設定連線，以指定傳入 FORMATETC 結構中感興趣的格式、外觀、中型和/或目標裝置。 如果數據物件完全不支援一或多個要求的屬性或傳送通知，則可以傳回OLE_E_ADVISENOTSUPPORTED來拒絕連線。

鏈接物件的容器可以直接設定與系結連結來源的諮詢連線，或透過管理連線的標準 OLE 連結物件間接設定。 Connections 系結連結來源設定時，不會自動刪除。 容器必須在系結連結來源上明確呼叫 IDataObject：:D Unadvise ，才能刪除諮詢連線。 透過 IOleLink 介面操作的 OLE 連結物件會在預設處理程式中實作。 Connections 刪除連結物件時，會終結透過 OLE 連結物件的設定。

OLE 預設連結物件會使用連結來源建立「通配符建議」，讓 OLE 可以維護上次變更的時間。 這項建議特別用來記下任何變更的時間。 OLE 會忽略可能已變更的所有數據格式，而不只是上次變更的時間。 若要允許通配符建議，請先依照下列方式設定 FORMATETC 成員，再呼叫 DAdvise：

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

建議旗標也應該包含ADVF_NODATA。 應用程式應一律接受來自 OLE 的通配符建議。

實作者的注意事項

為了簡化 IDataObject (DUnadvise 和 EnumDAdvise) 中實作 DAdvise 和其他通知方法的實作，OLE 提供可管理通知註冊和傳送通知的建議持有者物件。 若要取得此物件的指標，請在第一次叫用 DAdvise 時呼叫 Helper 函式 CreateDataAdviseHolder。 這會提供物件的 IDataAdviseHolder 介面指標。 然後，在數據建議持有者中委派 對 IDataAdviseHolder：：Advise 方法的呼叫，這會建立並後續管理要求的連線。

規格需求

需求 值
最低支援的用戶端 Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器 Windows 2000 Server [僅限桌面應用程式]
目標平台 Windows
標頭 objidl.h

另請參閱

CreateDataAdviseHolder

IAdviseSink：：OnDataChange

IDataObject