CoLockObjectExternal 函数 (combaseapi.h)

  • 项目

调用 可锁定对象以确保其保留在内存中，或释放此类锁。

语法

HRESULT CoLockObjectExternal(
  [in] LPUNKNOWN pUnk,
  [in] BOOL      fLock,
  [in] BOOL      fLastUnlockReleases
);

参数

[in] pUnk

指向要锁定或解锁的对象上的 IUnknown 接口的指针。

[in] fLock

指示是锁定还是释放对象。 如果此参数为 TRUE，则对象将保留在内存中，与 AddRef/发布 操作、注册或吊销无关。 如果此参数为 FALSE，则会释放以前通过调用此函数设置的锁。

[in] fLastUnlockReleases

如果锁是应使对象保持活动状态的最后一个引用，请指定 TRUE 释放指向对象的所有指针， (可能存在其他引用不应使其保持活动状态) 。 否则，请指定 FALSE。

如果 fLock 为 TRUE，则忽略此参数。

返回值

此函数可以返回E_INVALIDARG、E_OUTOFMEMORY、E_UNEXPECTED和S_OK的标准返回值。

注解

必须在对象实际驻留的进程中调用 CoLockObjectExternal 函数 (EXE 进程，而不是) 加载处理程序的进程。

CoLockObjectExternal 函数可防止对象的引用计数变为零，从而在释放锁之前将其“锁定”为存在。 同一函数 (具有不同参数) 释放锁。 锁是通过让系统在 对象上调用 IUnknown：：AddRef 来实现的。 然后，系统等待对对象调用 IUnknown：：Release，直到稍后调用 fLock 设置为 FALSE 的 CoLockObjectExternal。 此函数可用于代表最终用户维护对象上的引用计数，因为它在对象外部执行操作，用户也一样。

最终用户可以显式控制应用程序的生存期，即使应用程序上有外部锁。 也就是说，如果用户决定关闭应用程序，它必须关闭。 如果存在外部锁 (（例如 CoLockObjectExternal) 设置的锁），应用程序可以调用 CoDisconnectObject 函数，以在关闭之前强制关闭这些连接。

调用 CoLockObjectExternal 对对象设置强锁。 强锁将对象保留在内存中，而弱锁则不会。 例如，在 OLE 嵌入的无提示更新期间，需要强锁。 嵌入对象的容器必须保留在内存中，直到更新过程完成。 还必须对应用程序对象进行强锁定，以确保应用程序在完成向客户端提供服务之前保持活动状态。 所有外部引用都对对象放置一个强引用锁。

CoLockObjectExternal 函数通常在以下情况下调用：

  • 对象服务器应调用 CoLockObjectExternal ，当 fLock 和 fLastLockReleases 变为可见时，它们都设置为 TRUE 。 此调用代表用户创建强锁。 应用程序关闭时，通过调用 CoLockObjectExternal 释放锁，并将 fLock 设置为 FALSE，将 fLastLockReleases 设置为 TRUE。
  • 还可以在实现 IOleContainer：：LockContainer 时使用对服务器上的 CoLockObjectExternal 的调用。
在 LockContainer 的实现中使用 CoLockObjectExternal 时，需要注意几个事项。 嵌入对象将在其容器上调用 LockContainer 以使其保持运行 (锁定) 在没有其他原因使其保持运行的情况下。 当嵌入对象变为可见时，容器必须通过调用 OleSetContainedObject 函数来削弱其与嵌入对象的连接，以便其他连接可能会影响该对象。

除非应用程序通过调用 CoLockObjectExternal 完全管理其应用程序和文档关闭的所有方面，否则容器必须在 LockContainer 中保留专用锁计数，以便在锁计数达到零且容器不可见时退出。 保持关闭的所有方面，从而避免保留专用锁计数，意味着每当出现以下情况之一时，都应调用 CoLockObjectExternal ：

  • 创建并销毁文档，或使文档可见或不可见。
  • 应用程序由用户启动和关闭。
  • 创建并销毁伪对象。
出于调试目的，保留应用程序上设置的外部锁数 (和解锁) 计数可能会很有用。

要求

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

另请参阅

IOleContainer：：LockContainer

OleSetContainedObject