OleCreateLinkEx 函数 (ole2.h)

项目
08/25/2023

通过支持更高效地实例化需要缓存多种格式的演示文稿或数据的容器中的对象，而不是 OleCreateLink 支持的单个格式，扩展了 OleCreateLink 功能。

语法

HRESULT OleCreateLinkEx(
  [in]  LPMONIKER       pmkLinkSrc,
  [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] pmkLinkSrc

指向要创建链接的对象的名字对象的指针。

[in] riid

对要返回的对象的接口标识符的引用。

[in] dwFlags

此参数可以是 0 或 OLECREATE_LEAVERUNNING (0x00000001) 。

[in] renderopt

取自 OLERENDER 枚举的值。

[in] cFormats

当 renderopt OLERENDER_FORMAT时，指示 rgFormatEtc 数组中 FORMATETC 结构的数量，必须至少为一个。在所有其他情况下，此参数必须为零。

[in] rgAdvf

OLERENDER_FORMAT renderopt 时，指向 DWORD 元素数组，其中每个元素都是 ADVF 枚举中的值的组合。此数组的每个元素作为 advf 参数传递给对 IOleCache：：Cache 或 IDataObject：:D Advise 的调用，具体取决于 pAdviseSink 是 NULL 还是非 NULL (请参阅下面的) 。在所有其他情况下，此参数必须为 NULL。

[in] rgFormatEtc

OLERENDER_FORMAT renderopt 时，指向 FORMATETC 结构的数组。当 pAdviseSink 为 NULL 时，此数组的每个元素都将作为 pFormatEtc 参数传递给对对象的 IOleCache：：Cache 的调用。这会填充由进程内对象处理程序管理的数据和呈现缓存， (通常是默认处理程序) 演示文稿或其他可缓存数据。当 pAdviseSink 为非 NULL 时，此数组的每个元素都将作为 pFormatEtc 参数传递给对 IDataObject：:D Advise 的调用。这允许调用方 (通常为 OLE 容器) 对从对象接收的数据执行自己的缓存或处理。

[in] lpAdviseSink

当 renderopt OLERENDER_FORMAT 时，可以是有效的 IAdviseSink 指针（指示自定义缓存或处理数据建议），也可以是 NULL，指示默认缓存数据格式。

[out] rgdwConnection

返回使用 IDataObject：:D Advise 为每个咨询连接注册 IAdviseSink 接口时返回的 dwConnection 值数组的位置;如果不需要返回的咨询连接，则返回 NULL。如果 pAdviseSink 为 NULL，此参数必须为 NULL。

[in] pClientSite

指向对象通过其容器请求服务的主接口的指针。此参数可以为 NULL，在这种情况下，调用方负责使用 IOleObject：：SetClientSite 尽快建立客户端站点。

[in] pStg

指向要用于对象的存储的指针，以及为其建立的任何默认数据或演示文稿缓存。

[out] ppvObj

接收 riid 中请求的接口指针的输出指针变量的地址。成功返回后，*ppvObj 包含新创建对象上请求的接口指针。

返回值

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

返回代码	说明
E_NOINTERFACE	提供的接口标识符无效。
E_INVALIDARG	一个或多个参数无效。

注解

对 OleCreateLink 的以下调用：

OleCreateLink(pmkLinkSrc, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

等效于对 OleCreateLinkEx 的以下调用：

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

(OleCreate 的现有实例化函数，在实例化期间，OleCreateFromFile、OleCreateFromData、OleCreateLink 、OleCreateLinkToFile 和 OleCreateLinkFromData) 在默认缓存位置 (在传入的 IStorage) 的“\001OlePresXXX”流中创建单个演示文稿或数据格式缓存。此外，当对象接下来进入运行状态时，必须创建这些缓存。由于大多数应用程序需要在至少两个演示文稿中缓存 (屏幕和打印机) ，并且可能需要缓存与处理程序不同的格式或位置的数据，因此应用程序通常必须多次启动和关闭对象服务器，以便在对象创建期间设置其数据缓存，即插入对象、插入文件中的对象、和粘贴对象。

这些创建函数的扩展版本可解决此问题。 OleCreateEx、OleCreateFromFileEx、 OleCreateFromDataEx、OleCreateLinkEx、OleCreateLinkToFileEx 和 OleCreateLinkFromDataEx 包含以下新参数：用于指示其他选项的 dwFlags、用于指示要缓存的格式数的 cFormats、来自 ADVF 枚举的 rgAdvf，用于指定要缓存的每种格式的建议标志、pAdviseSink指示表示 (默认处理程序) 或数据 (非默认处理程序) 缓存是必需的，rgdwConnection 返回 IDataObject：:D Advise cookies，以及 rgFormatEtc（格式数组而不是单个格式）。

要求由对象的处理程序代表它们缓存多个演示文稿的容器，只需调用这些函数并指定 cFormats 中的格式数、rgAdvf 中每种格式的 ADVF 标志以及 rgFormatEtc 中的格式集。这些容器为 pAdviseSink 传递 NULL。

执行自己的所有数据缓存或演示文稿缓存的容器执行这些步骤，但会传递非 NULLpAdviseSink。它们在 IAdviseSink：：OnDataChange 期间对对象或数据执行自己的缓存或操作。通常，此类容器永远不会与ADVF_NODATA建立咨询连接，尽管不会阻止它们这样做。

这些新函数适用于 OLE 复合文档。使用这些函数，应用程序可以避免当前函数所需的重复启动和初始化步骤。它们针对使用默认数据和呈现缓存的 OLE 复合文档容器应用程序，以及从基础 IDataObject：:D Advise 支持提供自己的缓存和数据传输的应用程序。

要求

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