OleCreateEx 函式 (ole2.h)

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

語法

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

參數

[in] rclsid

識別要建立之 對象的類別。

[in] riid

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

[in] dwFlags

此值可以是 0 或 OLECREATE_LEAVERUNNING (0x00000001) 。

[in] renderopt

取自 OLERENDER 列舉的值。

[in] cFormats

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

[in] rgAdvf

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

[in] rgFormatEtc

當 renderopt OLERENDER_FORMAT時，指向 cFormats FORMATETC 結構的陣列。 當 pAdviseSink 為 NULL 時，此陣列的每個元素都會當做 pFormatEtc 參數傳遞至物件的 IOleCache：：Cache 呼叫。 這會填入物件同進程處理程式所管理的數據和簡報快取， (通常是使用簡報或其他可快取數據) 的默認處理程式。 當 pAdviseSink 不是 NULL 時，此陣列的每個元素都會當做 pFormatEtc 參數傳遞至 IDataObject：:D Advise 的呼叫。 這可讓呼叫端 (通常是 OLE Container) 自行快取或處理從 物件接收的數據。 在所有其他情況下，此參數必須是 NULL。

[in] lpAdviseSink

當 renderopt OLERENDER_FORMAT時，可能是有效的 IAdviseSink 指標，指出自定義快取或處理數據建議，或 NULL，表示數據格式的預設快取。 在所有其他情況下，此參數必須是 NULL。

[out] rgdwConnection

使用 IDataObject：:D AdviseSink 連接註冊 pAdviseSink 介面時，傳回 dwConnection 值陣列的位置，如果不需要傳回的諮詢連線，則為 NULL。 如果 pAdviseSink 為 NULL，就必須是 NULL。

[in] pClientSite

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

[in] pStg

要用於物件的記憶體指標，以及為其建立的任何預設數據或簡報快取。 此參數可能不是 NULL。

[out] ppvObj

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

傳回值

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

備註

下列對 OleCreate 的呼叫：

OleCreate(rclsid, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

相當於對 OleCreateEx 的下列呼叫：

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

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

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

要求對象處理程式代表多個簡報快取的容器可以直接呼叫這些函式，並指定 cFormats 中的格式數目、rgAdvf 中每個格式的 ADVF 旗標，以及 pFormatEtc 中的一組格式。 這些容器會傳遞 pAdviseSink 的 NULL。

執行自己所有數據或簡報快取的容器會執行這些相同的步驟，但會傳遞非 NULLpAdviseSink。 他們會在 IAdviseSink：：OnDataChange 期間，對對象或數據執行自己的快取或操作。 這類容器通常永遠不會建立與ADVF_NODATA的諮詢連線，但不會防止它們這麼做。

這些新函式適用於 OLE 複合檔。 使用這些函式，應用程式可以避免目前函式所需的重複啟動和初始化步驟。 它們以使用預設數據和簡報快取的 OLE 複合檔案容器應用程式為目標，也以從基礎 IDataObject：:D Advise 支援提供自己的快取和數據傳輸的應用程式為目標。

規格需求

另請參閱

ADVF

FORMATETC

IAdviseSink：：OnDataChange

IDataObject：:D Advise

IOleCache：：Cache

IOleObject：：SetClientSite

IStorage

OLERENDER

OleCreate