OleCreateFromFileEx 函式 (ole2.h)

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

語法

HRESULT OleCreateFromFileEx(
  [in]  REFCLSID        rclsid,
  [in]  LPCOLESTR       lpszFileName,
  [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

此參數是保留的，而且必須CLSID_NULL。

[in] lpszFileName

應該從中初始化新對象的檔名指標。

[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，表示數據格式的預設快取。

[out] rgdwConnection

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

[in] pClientSite

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

[in] pStg

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

[out] ppvObj

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

傳回值

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

備註

下列 OleCreateFromFile 呼叫：

OleCreateFromFile(rclsid, lpszFileName, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

相當於對 OleCreateFromFileEx 的下列呼叫：

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

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

規格需求

另請參閱

ADVF

FORMATETC

IAdviseSink：：OnDataChange

IDataObject：:D Advise

IOleCache：：Cache

IOleObject：：SetClientSite

IStorage

OLERENDER

OleCreateFromFile