IOleObject::D oVerb 方法 (oleidl.h)

为了响应最终用户的操作而请求对象执行某个操作。 为 IOleObject::EnumVerbs 中的 对象枚举可能的操作。

语法

HRESULT DoVerb(
  [in] LONG           iVerb,
  [in] LPMSG          lpmsg,
  [in] IOleClientSite *pActiveSite,
  [in] LONG           lindex,
  [in] HWND           hwndParent,
  [in] LPCRECT        lprcPosRect
);

参数

[in] iVerb

由 IOleObject::EnumVerbs 返回的 OLEVERB 结构中分配给谓词的数字。

[in] lpmsg

指向 MSG 结构的指针,该结构描述事件 (,例如双击调用谓词的) 。 调用方应传递未修改的 MSG 结构,而不尝试解释或更改任何结构成员的值。

[in] pActiveSite

指向对象的活动客户端站点上的 IOleClientSite 接口的指针,其中发生了调用谓词的事件。

[in] lindex

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

[in] hwndParent

包含该对象的文档窗口的句柄。 通过此和 lprcPosRect ,可以打开对象的临时窗口,其中 hwndParent 是对象窗口要在其中显示的父窗口, lprcPosRect 定义可用于在该父级内显示对象窗口的区域。 例如,临时窗口对于打开自身进行播放但不用于编辑的多媒体对象非常有用。

[in] lprcPosRect

指向 RECT 结构的指针,该结构包含以像素为单位的坐标,这些坐标在 hwndParent 中定义对象的边界矩形。 此和 hwndParent 一起支持打开多媒体对象进行播放,但不能用于编辑。

返回值

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

返回代码 说明
OLE_E_NOT_INPLACEACTIVE
iVerb 设置为 OLEIVERB_UIACTIVATE 或 OLEIVERB_INPLACEACTIVATE 且 对象尚不可见。
OLE_E_CANT_BINDTOSOURCE
对象处理程序或链接对象无法连接到链接源。
DV_E_LINDEX
无效的 lindex。
OLEOBJ_S_CANNOT_DOVERB_NOW
谓词有效,但在对象的当前状态下,它无法执行相应的操作。
OLEOBJ_S_INVALIDHWND
DoVerb 成功,但 hwndParent 无效。
OLEOBJ_E_NOVERBS
对象不支持任何谓词。
OLEOBJ_S_INVALIDVERB
链接源跨未连接到此计算机上的驱动器的网络。
MK_E_CONNECT
链接源跨未连接到此计算机上的驱动器的网络。
OLE_E_CLASSDIFF
链接源的类已进行转换。
E_NOTIMPL
对象不支持就地激活或无法识别负谓词编号。

注解

“谓词”是 OLE 对象为响应来自其容器的消息而采取的操作。 对象的容器或链接到对象的客户端通常调用 IOleObject::D oVerb 以响应某些最终用户操作,例如双击对象。 可用于给定对象的各种操作在 OLEVERB 结构中枚举,容器通过调用 IOleObject::EnumVerbs 获取该结构。 IOleObject::D oVerb 将 iVerb 的值与结构的 iVerb 成员匹配,以确定要调用哪个谓词。

通过 IOleObject::EnumVerbs,对象(而不是其容器)确定 (谓词,即) 它支持的操作。 OLE 2 定义了七个对所有对象都可用但不一定有用的谓词。 此外,每个对象都可以定义其唯一的其他谓词。 下表描述了 OLE 定义的谓词。

谓词 说明
OLEIVERB_PRIMARY (0L) 指定最终用户在其容器中双击对象时发生的操作。 对象(而不是容器)确定此操作。 如果对象支持就地激活,则主要谓词通常会就地激活对象。
OLEIVERB_SHOW (-1) 指示对象显示自身进行编辑或查看。 调用 以显示新插入的对象以进行初始编辑并显示链接源。 通常是其他某个对象定义谓词的别名。
OLEIVERB_OPEN (-2) 指示对象(包括支持就地激活的对象)在独立于其容器的窗口中打开自身进行编辑。 如果 对象不支持就地激活,则此谓词的语义与 OLEIVERB_SHOW 相同。
OLEIVERB_HIDE (-3) 导致对象从视图中删除其用户界面。 仅适用于就地激活的对象。
OLEIVERB_UIACTIVATE (-4) 在容器窗口的标题栏中激活对象及其完整的用户界面工具集,包括菜单、工具栏及其名称。 如果 对象不支持就地激活,则它应返回E_NOTIMPL。
OLEIVERB_INPLACEACTIVATE (-5) 在不显示最终用户需要更改对象行为或外观的工具(如菜单和工具栏)的情况下就地激活对象。 单击此类对象会导致它与其容器协商其用户界面工具的显示。 如果容器拒绝,对象将保持活动状态,但不显示其工具。
OLEIVERB_DISCARDUNDOSTATE (-6) 用于告知对象放弃它们可能维护的任何撤消状态,而不停用对象。
 

给调用方的说明

容器在初始化新创建的对象时调用 IOleObject::D oVerb 。 在调用之前,容器应首先调用 IOleObject::SetClientSite 以通知对象其显示位置, 并调用 IOleObject::SetHostNames 来提醒对象它是嵌入对象,并触发对对象应用程序的用户界面的相应更改,以准备打开编辑窗口。

IOleObject::D oVerb 自动运行 OLE 服务器应用程序。 如果在谓词执行期间发生错误,则会关闭对象应用程序。

如果最终用户通过某种方式调用谓词,而不是通过从菜单中选择命令 (说,通过双击或更罕见地单击对象) ,则对象的容器应将指针传递到包含相应消息的 Windows MSG 结构。 例如,如果最终用户通过双击 对象调用谓词,则容器应传递包含WM_LBUTTONDBLCLK、WM_MBUTTONDBLCLK或WM_RBUTTONDBLCLK的 MSG 结构。 如果容器未传递任何消息,则应将 lpmsg 设置为 NULL。 对象应忽略传递的 MSG 结构的 hwnd 成员,但可以使用所有其他 MSG 成员。

如果对象的嵌入容器调用 IOleObject::D oVerb,则传递给 IOleObject::D oVerb 的客户端站点指针 (pClientSite) 与嵌入站点的指针相同。 如果嵌入对象是链接源,则传递给 IOleObject::D oVerb 的指针是链接客户端的客户端站点的指针。

在 OLE 链接上调用 IOleObject::D oVerb 时,它可能会返回OLE_E_CLASSDIFF或MK_CONNECTMANUALLY。 链接对象在链接处于被动状态时,如果链接源已接受某种转换,则链接对象将返回以前的错误。 当链接源位于当前未连接到调用方计算机的网络驱动器上时,链接对象将返回后一个错误。 在这些条件下连接链接的唯一方法是首先调用 IUnknown::QueryInterface,请求 IOleLink,分配绑定上下文,并通过调用 IOleLink::BindToSource 运行链接源。

不支持常规就地激活的容器应用程序仍然可以使用 hwndParentlprcPosRect 参数来支持多媒体文件的就地播放。 容器必须将有效的 hwndParentlprcPosRect 参数传递给 IOleObject::D oVerb

某些代码示例传递的 lindex 值为 -1,而不是零。 值 -1 有效,但应避免使用 0。 lindex 参数是保留参数,出于一致性原因,Microsoft 建议为所有保留参数分配零值。

实施者说明

除了上述谓词,对象还可以在其 OLEVERB 结构中定义特定于自身的其他谓词。 正数指定这些特定于对象的谓词。 对象应将任何未知的正谓词视为主谓词,并将OLEOBJ_S_INVALIDVERB返回给调用函数。 对象应忽略具有其无法识别的负数的谓词,并返回E_NOTIMPL。

如果要执行的谓词将对象置于运行状态,则应在运行的对象表中注册该对象, (ROT) 即使其服务器应用程序不支持链接也是如此。 注册很重要,因为对象在某些时候可能充当容器中支持嵌入链接的链接的源。 将对象注册到 ROT 使链接客户端能够直接获取指向对象的指针,而不必通过对象的容器。 若要执行注册,请调用 IOleClientSite::GetMoniker 以获取对象的完整名字对象,调用 GetRunningObjectTable 函数以获取指向 ROT 的指针,然后调用 IRunningObjectTable::Register

注意 当对象离开运行状态时,请记得通过调用 IOleObject::Close 撤销对象在 ROT 中的注册。 如果在对象运行时重命名了对象的容器文档,则应撤销对象的注册,并使用其新名称将其重新注册到 ROT。 容器应通过调用 IOleObject::SetMoniker 或通过响应对象的调用 IOleClientSite::GetMoniker 来通知对象其新名字对象。
 
当将窗口显示为 IOleObject::D oVerb 的结果时,对象在其编辑窗口中显式调用 SetForegroundWindow 非常重要。 这可以确保对象的窗口对用户可见,即使另一个进程最初遮盖了它。 有关详细信息,请参阅 SetForegroundWindowSetActiveWindow

要求

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

另请参阅

GetRunningObjectTable

IOleClientSite::GetMoniker

IOleLink::BindToSource

IOleObject

IOleObject::Close

IOleObject::EnumVerbs

IOleObject::GetMoniker

IOleObject::SetMoniker

IRunningObjectTable::Register

OleRun