CoLockObjectExternal

9/8/2008

Essa função é chamado para bloqueio um objeto para garantir que ele permanece na memória ou a versão tal um bloqueio. Chamar CoLockObjectExternal Para um bloqueio de alta segurança em um objeto para garantir que ele permanece na memória local.

Syntax

STDAPI CoLockObjectExternal(
  IUnknown* pUnk,
  BOOL fLock,
  BOOL fLastUnlockReleases
);

Parameters

• pUnk
  [no] Ponteiro para o IUnknown interface sobre o objeto a ser bloqueados ou desbloqueados.

• fLock
  [no] Se o objeto deve ser bloqueada ou liberada. Especificar TRUE contém uma referência para o objeto (mantê-lo em memória), bloqueando-independently of externo ou interno AddRef/versão operações, registros ou revocations.

  Se fLock é TRUE, fLastLockReleases será ignorado.

  FALSE libera um bloqueio definido anteriormente com um chamar para essa função.

• fLastUnlockReleases
  [no] Se um determinado bloqueio é a última referência que deveria ser manter um objeto Alive. Se for, TRUE libera todos os ponteiros para o objeto (pode haver outras referências que não deveriam para manter-Alive).

Return Value

O padrão oferece suporte a essa função retornar valores E_INVALIDARG, E_OUTOFMEMORY e E_UNEXPECTED, bem como o seguinte:

• S_OK
  O objeto foi bloqueado com êxito.

Remarks

O CoLockObjectExternal função impede ir para zero, assim a contagem de referência de um objeto bloqueando-lo em existência até que o bloqueio é lançado.

A mesma função (com diferentes parâmetros) libera o bloqueio. O bloqueio é implementado por precisar chamar o sistema IUnknown::AddRef Sobre o objeto.

O sistema aguarda, em seguida, para chamar IUnknown::Release Sobre o objeto até que um chamar posterior para CoLockObjectExternal Com fLock definido como FALSE.

Esta função pode ser usada para manter um contagem de referência sobre o objeto on Behalf Of o usuário final, porque ele atua outside of o objeto, como o usuário.

O CoLockObjectExternal função deve ser chamado no processo no qual o objeto reside realmente (o processo exe, não o processo no qual manipuladores podem ser carregados).

Chamando CoLockObjectExternal Define um bloqueio de alta segurança em um objeto. Um bloqueio de alta segurança mantém um objeto na memória, enquanto um bloqueio fraco não. Bloqueios de alta segurança são exigido, de exemplo, durante uma atualização silenciosa para incorporação uma OLE.

Contêiner do objeto incorporado deve permanecer na memória até que o processo atualização esteja completo. Também deve haver um bloqueio de alta segurança em um objeto aplicativo para garantir que o aplicativo permanece ativo até que ele tenha terminado fornecendo serviços a seus clientes.

Externo todas as referências local uma forte referência bloqueio em um objeto.

O CoLockObjectExternal função é geralmente chamado no seguinte situações:

• Servidores de Objeto devem chamar CoLockObjectExternal Com ambas fLock e fLastLockReleases definido para TRUE quando eles estiverem visíveis. Este chamar cria um bloqueio de alta segurança on Behalf Of o usuário. Quando o aplicativo está fechando, livre de bloqueio com um chamar para CoLockObjectExternal, configuração fLock para FALSE e fLastLockReleases para TRUE.
• Um chamar para CoLockObjectExternal Sobre o servidor também pode ser usado na implementação de IOleContainer::LockContainer.

Existem várias coisas estar ciente de quando usar CoLockObjectExternal Na implementação de IOleContainer::LockContainer.

Seria uma objeto incorporado chamar IOleContainer::LockContainer No seu contêiner para manter-execução (para bloqueio-lo) na ausência de outros motivos para manter-execução.

Quando o objeto incorporado fica visível, o contêiner deve diminuir sua conexão para o objeto incorporado com um chamar para o OleSetContainedObject função, portanto, outras conexões podem afetar o objeto.

A menos que um aplicativo gerencia todos os aspectos do seu aplicativo e documento desligamento completamente com chamadas para CoLockObjectExternal, o contêiner deve manter um contagem de bloqueio particulares no IOleContainer::LockContainer Para que ele sai quando a contagem bloqueio atinge zero e o contêiner é invisível.

Manter todos os aspectos de desligamento e evitando, assim, manter um contagem de bloqueio particular, significa que CoLockObjectExternal deve ser chamado sempre que um das seguinte condições ocorrer:

• Um documento é criado e destruído ou feito visíveis ou invisíveis.
• Um aplicativo é iniciado e desligado, o usuário.
• Um pseudo-Object é criado e destruído.

Para depuração fins, pode ser útil para manter uma contagem do número de externo bloqueia (e desbloqueia) definido no aplicativo.

O usuário final terá controle explícito sobre a tempo de vida de um aplicativo, mesmo se não houver externo protege nele. Isto é, se um usuário decide fechar (o aplicativoArquivo, Sair), ele deverá desligar.

In the Presence of externo bloqueios (such as o bloqueio definido por CoLockObjectExternal), o aplicativo pode chamar o CoDisconnectObject função para forçar dessas conexões para fechar prior to desligamento.

Para determinar se a plataforma oferece suporte a essa função, consulte Determinando suporte COM APIs.

Requirements

Header	objbase.h
Library	ole32.lib
Windows Embedded CE	Windows CE 3.0 and later
Windows Mobile	Windows Mobile Version 5.0 and later

See Also

Reference

COM Functions