Função CoLockObjectExternal (combaseapi.h)

Chamado para bloquear um objeto para garantir que ele permaneça na memória ou para liberar esse bloqueio.

Sintaxe

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

Parâmetros

[in] pUnk

Um ponteiro para a interface IUnknown no objeto a ser bloqueado ou desbloqueado.

[in] fLock

Indica se o objeto deve ser bloqueado ou liberado. Se esse parâmetro for TRUE, o objeto será mantido na memória, independentemente das operações, registros ou revogações do AddRef/Release . Se esse parâmetro for FALSE, o bloqueio definido anteriormente com uma chamada para essa função será liberado.

[in] fLastUnlockReleases

Se o bloqueio for a última referência que deve manter um objeto ativo, especifique TRUE para liberar todos os ponteiros para o objeto (pode haver outras referências que não devem mantê-lo ativo). Caso contrário, especifique FALSE.

Se fLock for TRUE, esse parâmetro será ignorado.

Retornar valor

Essa função pode retornar os valores retornados padrão E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED e S_OK.

Comentários

A função CoLockObjectExternal deve ser chamada no processo no qual o objeto realmente reside (o processo EXE, não o processo no qual os manipuladores podem ser carregados).

A função CoLockObjectExternal impede que a contagem de referência de um objeto vá para zero, "bloqueando" a existência até que o bloqueio seja liberado. A mesma função (com parâmetros diferentes) libera o bloqueio. O bloqueio é implementado fazendo com que o sistema chame IUnknown::AddRef no objeto . Em seguida, o sistema aguarda para chamar IUnknown::Release no objeto até uma chamada posterior para CoLockObjectExternal com fLock definido como FALSE. Essa função pode ser usada para manter uma contagem de referência no objeto em nome do usuário final, pois atua fora do objeto, assim como o usuário.

O usuário final tem controle explícito sobre o tempo de vida de um aplicativo, mesmo que haja bloqueios externos nele. Ou seja, se um usuário decidir fechar o aplicativo, ele deverá ser desligado. Na presença de bloqueios externos (como o bloqueio definido por CoLockObjectExternal), o aplicativo pode chamar a função CoDisconnectObject para forçar essas conexões a fecharem antes do desligamento.

Chamar CoLockObjectExternal define um bloqueio forte em um objeto . Um bloqueio forte mantém um objeto na memória, enquanto um bloqueio fraco não. Bloqueios fortes são necessários, por exemplo, durante uma atualização silenciosa para uma inserção OLE. O contêiner do objeto inserido deve permanecer na memória até que o processo de atualização seja concluído. Também deve haver um bloqueio forte em um objeto de aplicativo para garantir que o aplicativo permaneça ativo até terminar de fornecer serviços aos clientes. Todas as referências externas colocam um forte bloqueio de referência em um objeto .

A função CoLockObjectExternal normalmente é chamada nas seguintes situações:

• Os servidores de objetos devem chamar CoLockObjectExternal com fLock e fLastLockReleases definidos como TRUE quando se tornarem visíveis. Essa chamada cria um bloqueio forte em nome do usuário. Quando o aplicativo estiver fechando, libere o bloqueio com uma chamada para CoLockObjectExternal, definindo fLock como FALSE e fLastLockReleases como TRUE.
• Uma chamada para CoLockObjectExternal no servidor também pode ser usada na implementação de IOleContainer::LockContainer.

Há várias coisas a serem consideradas quando você usa CoLockObjectExternal na implementação de LockContainer. Um objeto inserido chamaria LockContainer em seu contêiner para mantê-lo em execução (para bloqueá-lo) na ausência de outros motivos para mantê-lo em execução. Quando o objeto inserido se torna visível, o contêiner deve enfraquecer sua conexão com o objeto inserido com uma chamada para a função OleSetContainedObject , para que outras conexões possam afetar o objeto.

A menos que um aplicativo gerencie todos os aspectos de seu aplicativo e o desligamento de documentos completamente com chamadas para CoLockObjectExternal, o contêiner deve manter uma contagem de bloqueio privado no LockContainer para que ele saia quando a contagem de bloqueios atingir zero e o contêiner fique invisível. Manter todos os aspectos do desligamento e, assim, evitar manter uma contagem de bloqueios privados significa que CoLockObjectExternal deve ser chamado sempre que uma das seguintes condições ocorrer:

• Um documento é criado e destruído ou tornado visível ou invisível.
• Um aplicativo é iniciado e desligado pelo usuário.
• Um pseudoobjeto é criado e destruído.

Para fins de depuração, pode ser útil manter uma contagem do número de bloqueios externos (e desbloqueios) definidos no aplicativo.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	combaseapi.h (inclua Objbase.h)
Biblioteca	Ole32.lib
DLL	Ole32.dll

Confira também

IOleContainer::LockContainer

Olesetcontainedobject