roGetAgileReference 函数 (combaseapi.h)

  • 项目

为给定接口指定的 对象创建敏捷引用。

语法

HRESULT RoGetAgileReference(
  [in]  AgileReferenceOptions options,
  [in]  REFIID                riid,
  [in]  IUnknown              *pUnk,
  [out] IAgileReference       **ppAgileReference
);

参数

[in] options

注册选项。

[in] riid

要为其获取敏捷引用的 对象的接口 ID。

[in] pUnk

指向要封装在敏捷引用中的接口的指针。 它必须与 riid 的类型相同。 它可以是指向进程内对象的指针，也可以是指向对象的代理的指针。

[out] ppAgileReference

对象的敏捷引用。 调用 Resolve 方法，将对象本地化到调用 Resolve 的单元中。

返回值

此函数可以返回其中一个值。

返回值 说明
S_OK
 函数已成功完成。
E_INVALIDARG
 中的 options 参数无效。
E_OUTOFMEMORY
 由于内存不足的情况，无法构造敏捷引用。
E_NOINTERFACE
 pUnk 参数不支持 riid 参数指定的接口 ID。
CO_E_NOT_SUPPORTED
 对象实现 INoMarshal 接口。

注解

对现有对象调用 RoGetAgileReference 函数，以请求对对象的敏捷引用。 对象可以是敏捷的，也可能不是敏捷的，但返回的 IAgileReference 是敏捷的。 敏捷引用可以传递到同一进程中的另一个单元，其中原始对象是使用 IAgileReference 接口检索的。

这在概念上类似于现有的全局接口表 (GIT) 。 获取 IAgileReference 并将其用于直接检索对象，而不是与 GIT 交互。 正如 GIT 仅按进程执行一样，敏捷引用是按进程进行，不能封送。

敏捷参考功能提供了比 GIT 的性能改进。 默认情况下，敏捷引用执行预先封送处理，如果从与创建敏捷引用的位置不同的单元中的敏捷引用检索对象，则会保存跨单元调用。 为了进一步提高性能， RoGetAgileReference 函数的用户可以使用同一接口创建 IAgileReference 并解析原始对象。 这将保存一个额外的 QueryInterface 调用，以便从已解析的对象获取所需的接口。

例如，你有一个名为 CDemoExample 的非敏捷对象，该对象实现 IDemo 和 IExample 接口。 调用 RoGetAgileReference 函数并传递 对象，IID_IDemo。 你将返回一个 IAgileReference 接口指针，该指针是敏捷的，因此你可以将其传递到其他单元。 在其他单元中，使用 IID_IExample 调用 Resolve 方法。 你得到一个 IExample 指针，你可以在此公寓内使用。 此 IExample 指针是连接到原始 CDemoExample 对象的 IExample 代理。 敏捷引用处理操作的复杂性，例如手动封送到流，并在单元边界的另一侧取消封送。

要求

要求 值
最低受支持的客户端 Windows 8.1 [桌面应用 |UWP 应用]
最低受支持的服务器 Windows Server 2012 R2 [桌面应用 |UWP 应用]
目标平台 Windows
标头 combaseapi.h
Library Ole32.lib
DLL Ole32.dll

另请参阅

AgileReferenceOptions

IAgileReference