Función CoLockObjectExternal (combaseapi.h)

Se llama a para bloquear un objeto para asegurarse de que permanece en memoria o para liberar este bloqueo.

Sintaxis

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

Parámetros

[in] pUnk

Puntero a la interfaz IUnknown del objeto que se va a bloquear o desbloquear.

[in] fLock

Indica si el objeto se va a bloquear o liberar. Si este parámetro es TRUE, el objeto se mantiene en memoria, independientemente de las operaciones addref/release , los registros o las revocaciones. Si este parámetro es FALSE, se libera el bloqueo establecido previamente con una llamada a esta función.

[in] fLastUnlockReleases

Si el bloqueo es la última referencia que se supone que mantiene activo un objeto, especifique TRUE para liberar todos los punteros al objeto (puede haber otras referencias que no se supone que lo mantengan activo). De lo contrario, especifique FALSE.

Si fLock es TRUE, se omite este parámetro.

Valor devuelto

Esta función puede devolver los valores devueltos estándar E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED y S_OK.

Comentarios

Se debe llamar a la función CoLockObjectExternal en el proceso en el que reside realmente el objeto (el proceso EXE, no el proceso en el que se pueden cargar los controladores).

La función CoLockObjectExternal impide que el recuento de referencias de un objeto vaya a cero, lo que lo "bloquea" hasta que se libere el bloqueo. La misma función (con parámetros diferentes) libera el bloqueo. El bloqueo se implementa haciendo que el sistema llame a IUnknown::AddRef en el objeto . A continuación, el sistema espera a llamar a IUnknown::Release en el objeto hasta que una llamada posterior a CoLockObjectExternal con fLock establecido enFALSE. Esta función se puede usar para mantener un recuento de referencias en el objeto en nombre del usuario final, ya que actúa fuera del objeto, como hace el usuario.

El usuario final tiene control explícito sobre la duración de una aplicación, incluso si hay bloqueos externos en ella. Es decir, si un usuario decide cerrar la aplicación, debe apagarse. En presencia de bloqueos externos (como el bloqueo establecido por CoLockObjectExternal), la aplicación puede llamar a la función CoDisconnectObject para forzar que estas conexiones se cierren antes del apagado.

Al llamar a CoLockObjectExternal , se establece un bloqueo seguro en un objeto . Un bloqueo fuerte mantiene un objeto en memoria, mientras que un bloqueo débil no. Se requieren bloqueos seguros, por ejemplo, durante una actualización silenciosa de una inserción OLE. El contenedor del objeto incrustado debe permanecer en memoria hasta que se complete el proceso de actualización. También debe haber un bloqueo seguro en un objeto de aplicación para asegurarse de que la aplicación permanece activa hasta que haya terminado de proporcionar servicios a sus clientes. Todas las referencias externas colocan un bloqueo de referencia seguro en un objeto .

Normalmente se llama a la función CoLockObjectExternal en las situaciones siguientes:

• Los servidores de objetos deben llamar a CoLockObjectExternal con fLock y fLastLockReleases establecidos en TRUE cuando se vuelven visibles. Esta llamada crea un bloqueo seguro en nombre del usuario. Cuando la aplicación se cierre, libere el bloqueo con una llamada a CoLockObjectExternal, estableciendo fLock enFALSE y fLastLockReleases en TRUE.
• También se puede usar una llamada a CoLockObjectExternal en el servidor en la implementación de IOleContainer::LockContainer.

Hay varios aspectos que debe tener en cuenta al usar CoLockObjectExternal en la implementación de LockContainer. Un objeto incrustado llamaría a LockContainer en su contenedor para mantenerlo en ejecución (para bloquearlo) en ausencia de otras razones para mantenerla en ejecución. Cuando el objeto incrustado se vuelve visible, el contenedor debe debilitar su conexión al objeto incrustado con una llamada a la función OleSetContainedObject , por lo que otras conexiones pueden afectar al objeto.

A menos que una aplicación administre todos los aspectos de su aplicación y cierre de documentos por completo con llamadas a CoLockObjectExternal, el contenedor debe mantener un recuento de bloqueos privado en LockContainer para que salga cuando el recuento de bloqueos alcance cero y el contenedor sea invisible. Mantener todos los aspectos del apagado y, por tanto, evitar mantener un recuento de bloqueos privados, significa que se debe llamar a CoLockObjectExternal siempre que se produzca una de las condiciones siguientes:

• Se crea un documento y se destruye o se hace visible o invisible.
• El usuario inicia y cierra una aplicación.
• Se crea y destruye un pseudoobjeto.

Con fines de depuración, puede ser útil mantener un recuento del número de bloqueos externos (y desbloqueos) establecidos en la aplicación.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	combaseapi.h (incluya Objbase.h)
Library	Ole32.lib
Archivo DLL	Ole32.dll

Consulte también

IOleContainer::LockContainer

OleSetContainedObject