Método IRunningObjectTable::Register (objidl.h)

  • Artigo

Registra um objeto e seu moniker de identificação na ROT (tabela de objetos em execução).

Sintaxe

HRESULT Register(
  [in]  DWORD    grfFlags,
  [in]  IUnknown *punkObject,
  [in]  IMoniker *pmkObjectName,
  [out] DWORD    *pdwRegister
);

Parâmetros

[in] grfFlags

Especifica se a referência do ROT ao punkObject é fraca ou forte e controla o acesso ao objeto por meio de sua entrada no ROT. Para obter detalhes, consulte a seção Comentários.

Valor Significado
ROTFLAGS_REGISTRATIONKEEPSALIVE
 Quando definido, indica um registro forte para o objeto .
ROTFLAGS_ALLOWANYCLIENT
 Quando definido, qualquer cliente pode se conectar ao objeto em execução por meio de sua entrada no ROT. Quando não definido, somente os clientes na estação de janela que registraram o objeto podem se conectar a ele.

[in] punkObject

Um ponteiro para o objeto que está sendo registrado como em execução.

[in] pmkObjectName

Um ponteiro para o moniker que identifica punkObject.

[out] pdwRegister

Um identificador para essa entrada ROT que pode ser usado em chamadas subsequentes para IRunningObjectTable::Revoke ou IRunningObjectTable::NoteChangeTime. O chamador não pode especificar NULL para esse parâmetro. Se ocorrer um erro, *pdwRegister será definido como zero.

Retornar valor

Esse método pode retornar os valores retornados padrão E_INVALIDARG e E_OUTOFMEMORY, bem como os valores a seguir.

Código de retorno Descrição
S_OK
 O método foi concluído com sucesso.
MK_S_MONIKERALREADYREGISTERED
 O par moniker/objeto foi registrado com êxito, mas que outro objeto (possivelmente o mesmo objeto) já foi registrado com o mesmo moniker.

Comentários

Esse método registra um ponteiro para um objeto sob um moniker que identifica o objeto. O moniker é usado como a chave quando a tabela é pesquisada com IRunningObjectTable::GetObject.

Quando um objeto é registrado, o ROT sempre chama AddRef no objeto . Para um registro fraco (ROTFLAGS_REGISTRATIONKEEPSALIVE não definido), o ROT liberará o objeto sempre que a última referência forte ao objeto for liberada. Para um registro forte (conjunto de ROTFLAGS_REGISTRATIONKEEPSALIVE), o ROT impede que o objeto seja destruído até que o registro do objeto seja explicitamente revogado.

Um servidor registrado como LocalService ou RunAs pode definir o sinalizador ROTFLAGS_ALLOWANYCLIENT em sua chamada para Registrar para permitir que qualquer cliente se conecte a ele. Uma configuração de servidor deste bit deve ter seu nome executável na seção AppID do registro que se refere ao AppID para o executável. Um servidor "ativar como ativador" (não registrado como LocalService ou RunAs) não deve definir esse sinalizador em sua chamada para Registrar. Para obter detalhes sobre como instalar serviços, consulte Instalando como um aplicativo de serviço.

Registrar um segundo objeto com o mesmo moniker ou registrar novamente o mesmo objeto com o mesmo moniker cria uma segunda entrada no ROT. Nesse caso, Register retorna MK_S_MONIKERALREADYREGISTERED. Cada chamada para Registrar deve ser correspondida por uma chamada para IRunningObjectTable::Revoke porque até mesmo entradas duplicadas têm identificadores pdwRegister diferentes. Um problema com registros duplicados é que não há como determinar qual objeto será retornado se o moniker for especificado em uma chamada subsequente para IRunningObjectTable::IsRunning.

Anotações aos Chamadores

Se você for um provedor de moniker (ou seja, distribuir monikers que identificam seus objetos para torná-los acessíveis a outras pessoas), deverá chamar o método Register para registrar seus objetos quando eles começarem a ser executados. Você também deve chamar esse método se renomear seus objetos enquanto eles são carregados.

O tipo mais comum de provedor de moniker é uma fonte de link de documento composto. Isso inclui aplicativos de servidor que dão suporte à vinculação a documentos (ou partes de um documento) e aplicativos de contêiner que dão suporte à vinculação a inserções em seus documentos. Aplicativos de servidor que não dão suporte à vinculação também podem usar o ROT para cooperar com aplicativos de contêiner que dão suporte à vinculação a inserções.

Se você estiver escrevendo um aplicativo de servidor, deverá registrar um objeto com o ROT quando ele começar a ser executado, normalmente em sua implementação de IOleObject::D oVerb. O objeto deve ser registrado sob seu moniker completo, o que requer a obtenção do moniker de seu documento de contêiner usando IOleClientSite::GetMoniker. Você também deve revogar e registrar novamente o objeto em sua implementação de IOleObject::SetMoniker, que será chamado se o documento de contêiner for renomeado.

Se você estiver escrevendo um aplicativo de contêiner que dê suporte à vinculação a inserções, registre seu documento com o ROT quando ele for carregado. Se o documento for renomeado, você deverá revogá-lo e registrá-lo novamente no ROT e chamar IOleObject::SetMoniker para quaisquer objetos inseridos no documento para dar a eles a oportunidade de se registrarem novamente.

Os objetos registrados no ROT devem ser explicitamente revogados quando o objeto não estiver mais em execução ou quando seu moniker for alterado. Essa revogação é importante porque não há como o sistema remover automaticamente as entradas do ROT. Você deve armazenar em cache o identificador gravado por meio de pdwRegister e usá-lo em uma chamada para IRunningObjectTable::Revoke para revogar o registro. Para um registro forte, uma referência forte é liberada quando o registro de objetos é revogado.

A partir do Windows Server 2003, se houver entradas obsoletas que permanecem no ROT devido a problemas inesperados do servidor, o COM removerá automaticamente essas entradas obsoletas do ROT.

A implementação do sistema de Registrar chama IMoniker::Reduce no parâmetro pmkObjectName para garantir que o moniker seja totalmente reduzido antes do registro. Se um objeto for conhecido por mais de um moniker totalmente reduzido, ele deverá ser registrado em todos esses monikers.

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 objidl.h

Confira também

Irunningobjecttable