OleCreateLinkFromDataEx 函式 (ole2.h)

藉由在需要快取多種簡報或資料的容器中支援更有效率的物件具現化，而不是OleCreateLinkFromData所支援的單一格式，來擴充OleCreateLinkFromData功能。

語法

HRESULT OleCreateLinkFromDataEx(
  [in]      LPDATAOBJECT    pSrcDataObj,
  [in]      REFIID          riid,
  [in]      DWORD           dwFlags,
  [in]      DWORD           renderopt,
  [in]      ULONG           cFormats,
  [in]      DWORD           *rgAdvf,
  [in]      LPFORMATETC     rgFormatEtc,
  [in]      IAdviseSink     *lpAdviseSink,
  [in, out] DWORD           *rgdwConnection,
  [in]      LPOLECLIENTSITE pClientSite,
  [in]      LPSTORAGE       pStg,
  [out]     LPVOID          *ppvObj
);

參數

[in] pSrcDataObj

要從中建立連結化物件之資料物件的指標。

[in] riid

要傳回之物件介面之識別碼的參考。

[in] dwFlags

此參數可以是 0 或 OLECREATE_LEAVERUNNING (0x00000001) 。

[in] renderopt

取自 OLERENDER 列舉的值。

[in] cFormats

當renderopt OLERENDER_FORMAT時，表示rgFormatEtc陣列中的FORMATETC結構數目，這至少必須是一個。 在其他所有情況下，此參數必須是零。

[in] rgAdvf

當 renderopt OLERENDER_FORMAT時，會指向 DWORD 元素的陣列，每個元素都是 ADVF 列舉中的值組合。 此陣列的每個元素都會當做 advf 參數傳入 呼叫 IOleCache：：Cache 或IDataObject：:D Advise，視 pAdviseSink 為 Null 或非Null (請參閱下方) 。 在其他所有情況下，此參數必須是 Null。

[in] rgFormatEtc

當 renderopt OLERENDER_FORMAT時，會指向 FORMATETC 結構的陣列。 當 pAdviseSink 為 Null時，此陣列的每個元素都會當做 pFormatEtc 參數傳遞至物件的 IOleCache：：Cache呼叫。 這會填入由同進程處理常式中物件所管理的資料和簡報快取， (通常是使用簡報或其他可快取資料) 的預設處理常式。 當 pAdviseSink 不是Null時，此陣列的每個元素都會當做 pFormatEtc 參數傳遞至 IDataObject：:D Advise的呼叫。 這可讓呼叫端 (通常是 OLE 容器) 自行快取或處理從 物件接收的資料。

[in] lpAdviseSink

當 renderopt 是OLERENDER_FORMAT時，可能是有效的 IAdviseSink 指標、指出自訂快取或處理資料建議，或是 Null，表示資料格式的預設快取。

[in, out] rgdwConnection

當pAdviseSink介面使用IDataObject：:D AdviseAdvise註冊每個諮詢連線時所傳回的 dwConnection值陣列的位置，如果不需要傳回的諮詢連線，則傳回Null。 如果pAdviseSink為Null，此參數必須為Null。

[in] pClientSite

物件從其容器要求服務的主要介面指標。 此參數可以是 Null，在此情況下，呼叫者必須負責儘快使用 IOleObject：：SetClientSite建立用戶端網站。

[in] pStg

要用於物件的儲存體指標，以及為其建立的任何預設資料或簡報快取。

[out] ppvObj

接收 riid 中所要求介面指標的輸出指標變數位址。 成功傳回時，*ppvObj 會在新建立的物件上包含要求的介面指標。

傳回值

此函式會在成功時傳回S_OK。 其他可能的值包括下列專案。

備註

下列 OleCreateLinkFromData呼叫：

OleCreateLinkFromData(pSrcDataObj, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

相當於對 OleCreateLinkFromDataEx的下列呼叫：

DWORD    advf = ADVF_PRIMEFIRST;
    OleCreateLinkFromDataEx(pSrcDataObj, riid, renderopt, 1, &advf, pFormatEtc, NULL, NULL, pClientSite, pStg, ppvObj);

現有的具現化函式 (OleCreate、OleCreateFromFile、OleCreateFromData、OleCreateLinkToFile和OleCreateLinkFromData) ，只在預設快取位置中建立單一簡報或資料格式快取， (具現化期間傳入IStorage) 的 '\001OlePresXXX' 資料流程內。 此外，當物件下次進入執行中狀態時，必須建立這些快取。 由於大部分的應用程式至少需要快取兩個簡報 (螢幕和印表機) ，而且可能需要從處理常式以不同的格式或位置快取資料，因此應用程式通常必須啟動和關閉物件服務器多次，才能在物件建立期間提供其資料快取，例如插入物件、從檔案插入物件、 插入物件、 和 Paste 物件。

這些建立函式的擴充版本可解決此問題。 OleCreateEx、OleCreateFromFileEx、 OleCreateFromDataEx、OleCreateLinkEx、OleCreateLinkToFileEx和OleCreateLinkFromDataEx包含下列新參數：dwFlags 表示其他選項，cFormats表示要從ADVF列舉快取多少格式、rgAdvf、指定要快取之每個格式的建議旗標，pAdviseSink表示是否需要簡報 (預設處理常式) 或資料 (非預設處理常式) 快取、rgdwConnection傳回IDataObject：:D Advise Cookie 和rgFormatEtc，這是格式陣列，而不是單一格式。

需要由物件處理常式代表多個簡報快取的容器可以直接呼叫這些函式，並以cFormats指定格式數目、rgAdvf中每個格式的ADVF旗標，以及rgFormatEtc中的一組格式。 這些容器會針對pAdviseSink傳遞Null。

執行自己所有資料或簡報快取的容器會執行這些相同的步驟，但會傳遞非NullpAdviseSink。 他們會在 IAdviseSink：：OnDataChange期間執行自己的物件或資料快取或操作。 這類容器通常永遠不會建立與ADVF_NODATA的諮詢連線，但無法這麼做。

這些新函式適用于 OLE 複合檔案。 使用這些函式，應用程式可以避免目前函式所需的重複啟動和初始化步驟。 它們的目標是使用預設資料和簡報快取的 OLE 複合檔案容器應用程式，以及提供自有 IDataObject：:D Advise 支援之自有快取和資料傳輸的應用程式。

需求

另請參閱

IAdviseSink：：OnDataChange

IDataObject：:D Advise

IOleCache：：Cache

IOleObject：：SetClientSite

OleCreate

OleCreateLinkFromData