IMarshal::MarshalInterface 方法 (objidlbase.h)

封送接口指针。

语法

HRESULT MarshalInterface(
  [in] IStream *pStm,
  [in] REFIID  riid,
  [in] void    *pv,
  [in] DWORD   dwDestContext,
  [in] void    *pvDestContext,
  [in] DWORD   mshlflags
);

参数

[in] pStm

指向封送处理期间要使用的流的指针。

[in] riid

对要封送的接口的标识符的引用。 此接口必须派生自 IUnknown 接口。

[in] pv

指向要封送的接口指针的指针。 如果调用方没有指向所需接口的指针,此参数可以为 NULL

[in] dwDestContext

要取消对指定接口进行封送的目标上下文。 dwDestContext 的可能值来自枚举 MSHCTX。 目前,拆收处理可以发生在当前进程 (MSHCTX_INPROC) 的另一个单元中,也可以发生在与当前进程 (MSHCTX_LOCAL) 相同计算机上的另一个进程中。

[in] pvDestContext

此参数是保留的,必须为 0。

[in] mshlflags

指示要封送的数据是传输回客户端进程(典型情况)还是写入全局表(可在其中由多个客户端检索)。 可能的值来自 MSHLFLAGS 枚举。

返回值

此方法可以返回E_FAIL的标准返回值,以及以下值。

返回代码 说明
S_OK
已成功封送接口指针。
E_NOINTERFACE
不支持指定的接口。
STG_E_MEDIUMFULL
流已满。

注解

在调用 CoMarshalInterface 时,由服务器进程中负责封送指向对象上接口的指针的任何代码间接调用此方法。 此封送代码通常是 COM 为多个接口之一生成的存根,这些接口可以封送指向在完全不同的对象上实现的接口的指针。 示例包括 IClassFactoryIOleItemContainer 接口。 出于讨论目的,负责封送指针的代码称为 封送存根

给调用方的说明

通常,封送处理存根应该调用 CoMarshalInterface 函数,该函数包含对此方法的调用,而不是直接调用 MarshalInterface。 存根发出此调用,以命令对象将其封送数据写入流。 然后,存根会将封送处理数据传递回客户端进程,或将其写入全局表,其中多个客户端可以取消封送数据。 存根对 CoMarshalInterface 的调用通常先调用 CoGetMarshalSizeMax ,以获取将封送数据写入其中的流缓冲区的最大大小。

如果要实现现有 COM 接口或使用 Microsoft 接口定义语言 (MIDL) 定义自己的接口,则不会显式调用此方法。 在任一情况下,MIDL 生成的存根都会自动进行调用。

如果不使用 MIDL 定义自己的接口,封送处理存根必须直接或间接调用此方法。 存根实现应在上一次调用 IMarshal::GetMarshalSizeMax 返回后立即调用 MarshalInterface。 由于 GetMarshalSizeMax 返回的值保证仅在被封送的对象的内部状态不更改时有效,因此调用 MarshalInterface 时出现延迟的风险是,对象需要比最初指示更大的流缓冲区。

如果调用方具有指向要封送的接口的指针,则为了提高效率,应使用 pv 参数传递该指针。 这样,可以使用此类指针来确定代理的适当 CLSID 的实现不必在自身上调用 QueryInterface 。 如果调用方没有指向要封送的接口的指针,它可以传递 NULL

实施者说明

MarshalInterface 的实现必须将初始化接收端代理所需的任何数据写入流。 此类数据将包括对要封送的接口的引用、一个 MSHLFLAGS 值,该值指定数据是应返回到客户端进程还是写入全局表,以及连接到对象所需的任何内容,例如命名管道、窗口句柄或指向 RPC 通道的指针。

实现不应假定流的大小足以容纳所有数据。 相反,它应正常处理STG_E_MEDIUMFULL错误。 在退出之前,实现应紧接在写入数据的最后一个字节之后的流中查找指针。

如果 pv 参数为 NULL 并且实现需要接口指针,则它可以在当前对象上调用 QueryInterface 来获取它。 pv 参数的存在只是为了提高效率。

为确保 MarshalInterface 的实现在将来支持新目标上下文时继续正常工作,请将封送处理委托给实现不处理的所有 dwDestContext 值的 COM 默认实现。 若要将封送处理委托给 COM 默认实现,请调用 CoGetStandardMarshal 帮助程序函数。

使用 MSHLFLAGS 枚举,调用方可以指定是将接口指针封送回单个客户端,还是写入全局表,其中的多个客户端可以取消封送。 必须确保对象可以处理来自多个代理的调用,这些代理可能从同一初始化数据创建。

要求

要求
最低受支持的客户端 Windows 2000 专业版 [桌面应用 |UWP 应用]
最低受支持的服务器 Windows 2000 Server [桌面应用 |UWP 应用]
目标平台 Windows
标头 objidlbase.h (包括 ObjIdl.h)

另请参阅

CoMarshalInterface

IMarshal