Interface IMoniker (objidl.h)

Artigo
03/15/2023

Permite que você use um objeto moniker, que contém informações que identificam exclusivamente um objeto COM. Um objeto que tem um ponteiro para a interface IMoniker do objeto moniker pode localizar, ativar e obter acesso ao objeto identificado sem ter nenhuma outra informação específica sobre onde o objeto está realmente localizado em um sistema distribuído.

Monikers são usados como base para vinculação no COM. Um objeto vinculado contém um moniker que identifica sua origem. Quando o usuário ativa o objeto vinculado para editá-lo, o moniker é associado; isso carrega a origem do link na memória.

Herança

A interface IMoniker herda de IPersistStream. O IMoniker também tem esses tipos de membros:

Métodos

A interface IMoniker tem esses métodos.


IMoniker::BindToObject Associa-se ao objeto especificado. O processo de associação envolve encontrar o objeto, colocá-lo no estado em execução, se necessário, e fornecer ao chamador um ponteiro para uma interface especificada no objeto identificado.
IMoniker::BindToStorage Associa-se ao armazenamento do objeto especificado. Ao contrário do método IMoniker::BindToObject, esse método não ativa o objeto identificado pelo moniker.
IMoniker::CommonPrefixWith Cria um novo moniker com base no prefixo que esse moniker tem em comum com o moniker especificado.
IMoniker::ComposeWith Cria um novo moniker composto combinando o moniker atual com o moniker especificado.
IMoniker::Enum Recupera um ponteiro para um enumerador para os componentes de um moniker composto.
IMoniker::GetDisplayName Recupera o nome de exibição do moniker.
IMoniker::GetTimeOfLastChange Recupera a hora em que o objeto identificado por esse moniker foi alterado pela última vez.
IMoniker::Hash Cria um valor de hash usando o estado interno do moniker.
IMoniker::Inverse Cria um moniker que é o inverso desse moniker. Quando composto à direita deste moniker ou de uma estrutura semelhante, o moniker será redigido a nada.
IMoniker::IsEqual Determina se esse moniker é idêntico ao moniker especificado.
IMoniker::IsRunning Determina se o objeto identificado por esse moniker está atualmente carregado e em execução.
IMoniker::IsSystemMoniker Determina se esse moniker é uma das classes de moniker fornecidas pelo sistema.
IMoniker::P arseDisplayName Converte um nome de exibição em um moniker.
IMoniker::Reduce Reduz um moniker à sua forma mais simples.
IMoniker::RelativePathTo Cria um moniker relativo entre esse moniker e o moniker especificado.

Comentários

Como um caminho para um arquivo em um sistema de arquivos, um moniker contém informações que permitem que um objeto COM seja localizado e ativado. Os monikers podem identificar qualquer tipo de objeto COM, desde um objeto de documento armazenado em um arquivo até uma seleção dentro de um objeto inserido. O COM fornece um conjunto de classes moniker que permitem criar objetos moniker que identificam os objetos mais comumente encontrados no sistema. Por exemplo, pode haver um objeto que representa um intervalo de células em uma planilha que está inserida em um documento de texto armazenado em um arquivo. Em um sistema distribuído, o moniker desse objeto identificaria o local do sistema do objeto, o local físico do arquivo nesse sistema, o armazenamento do objeto inserido dentro desse arquivo e, por fim, o local do intervalo de células dentro do objeto inserido.

Um objeto moniker dá suporte à interface IMoniker , que é derivada da interface IPersistStream e identifica exclusivamente um único objeto no sistema. Depois que um objeto que fornece um moniker tiver criado o objeto moniker, essas informações não poderão ser alteradas dentro desse objeto. Se o provedor de moniker alterar as informações, ele só poderá fazer isso criando um novo objeto moniker, que identificaria exclusivamente o objeto em questão.

Os monikers têm os dois recursos importantes a seguir:

Monikers podem ser salvos em um armazenamento persistente. Quando um moniker é carregado novamente na memória, ele ainda identifica o mesmo objeto.
Os monikers dão suporte a uma operação chamada associação, que é o processo de localizar o objeto chamado pelo moniker, ativá-lo (carregá-lo na memória) se ele ainda não estiver ativo e retornar um ponteiro para uma interface solicitada nesse objeto.

Implementação anti-Moniker

Os anti-monikers são o inverso das implementações COM de monikers de arquivo, item e ponteiro. Ou seja, um anti-moniker composto à direita de um moniker de arquivo, moniker de item ou moniker de ponteiro compõe para nada.

Se você for um cliente moniker, normalmente não precisará usar anti-monikers. Quando precisar do inverso de um moniker, você deve chamar IMoniker::Inverse. Por exemplo, se você precisar de um inverso para remover a última parte de um moniker composto, use IMoniker::Enum para enumerar as partes do moniker e chamar Inverso na peça mais à direita. Você não deve usar um anti-moniker para essa finalidade porque não pode ter certeza de que a parte mais correta de uma composição considera um anti-moniker como seu inverso.

A única situação em que você deve usar explicitamente um anti-moniker é quando você está escrevendo uma nova classe moniker e não tem requisitos especiais para construir inversos aos seus monikers. Nessa situação, você pode retornar anti-monikers da implementação do Inverso. Em sua implementação de IMoniker::ComposeWith, você deve então aniquilar um de seus monikers para cada anti-moniker que encontrar.

Use a função CreateAntiMoniker para criar esses monikers.

Implementação do Moniker de Classe

Monikers de classe são monikers que representam uma classe de objeto. Monikers de classe são associados ao objeto de classe da classe para a qual são criados.

Monikers de classe são mais úteis na composição com outros tipos de monikers, como monikers de arquivo ou monikers de item. Monikers de classe também podem ser compostos à direita de monikers que dão suporte à associação à interface IClassActivator . Isso permite que o IClassActivator forneça acesso ao objeto de classe e às instâncias da classe .

Para usar monikers de classe, você deve usar a função CreateClassMoniker para criar esses monikers.

Implementação do Moniker de Arquivo

Monikers de arquivo são monikers que representam um caminho no sistema de arquivos; um moniker de arquivo pode identificar qualquer objeto salvo em seu próprio arquivo. Para identificar objetos contidos em um arquivo, você pode compor monikers de outras classes (por exemplo, monikers de item) à direita de um moniker de arquivo. No entanto, o moniker à esquerda de um moniker de arquivo dentro de uma composição deve ser outro moniker de arquivo, um anti-moniker ou um moniker de classe. É ilegal, por exemplo, que um moniker de item apareça à esquerda de um moniker de arquivo em uma composição.

Observe que um anti-moniker é o inverso de um moniker de arquivo inteiro, não o inverso de um componente do caminho que o moniker representa; ou seja, quando você compõe um anti-moniker à direita de um moniker de arquivo, todo o moniker de arquivo é removido. Se você quiser remover apenas o componente mais à direita do caminho representado por um moniker de arquivo, crie um moniker de arquivo separado com base no caminho ".." e, em seguida, redigir isso até o final do moniker de arquivo.

Um cliente moniker (usando um moniker para obter um ponteiro de interface para um objeto) normalmente não precisa conhecer a classe do moniker; ele pode simplesmente chamar métodos usando um ponteiro de interface IMoniker .

Um provedor de moniker (distribuindo monikers que identificam seus objetos para torná-los acessíveis a clientes moniker) deve usar monikers de arquivo se os objetos que eles estão identificando estiverem armazenados em arquivos. Se cada objeto residir em seu próprio arquivo, os monikers de arquivo serão o único tipo necessário. Se os objetos identificados forem menores que um arquivo, você precisará usar outro tipo de moniker (por exemplo, monikers de item) além de monikers de arquivo.

Para usar monikers de arquivo, você deve usar a função CreateFileMoniker para criar os monikers. Para permitir que seus objetos sejam carregados quando um moniker de arquivo estiver associado, seus objetos devem implementar a interface IPersistFile .

O exemplo mais comum de provedores de moniker são aplicativos de servidor COM que dão suporte à vinculação. Se o aplicativo de servidor COM der suporte à vinculação somente a documentos baseados em arquivo em sua totalidade, os monikers de arquivo serão o único tipo de moniker necessário. Se o aplicativo do servidor COM der suporte à vinculação a objetos menores que um documento (como seções de um documento ou objetos inseridos), você deverá usar monikers de item, bem como monikers de arquivo.

Implementação de moniker composto genérico

Um moniker composto genérico é um moniker composto cujos componentes não têm conhecimento especial uns dos outros.

A composição é o processo de unir dois monikers. Às vezes, dois monikers de classes específicas podem ser combinados de maneira especial; por exemplo, um moniker de arquivo que representa um caminho incompleto e outro moniker de arquivo que representa um caminho relativo pode ser combinado para formar um único moniker de arquivo que representa o caminho completo. Este é um exemplo de composição não genérica. A composição genérica, por outro lado, pode conectar dois monikers, independentemente de suas classes. Como uma composição não genérica depende da classe dos monikers envolvidos, ela só pode ser executada pela implementação de uma determinada classe do método IMoniker::ComposeWith . Você pode definir novos tipos de composições não genéricas se escrever uma nova classe moniker. Por outro lado, composições genéricas são executadas pela função CreateGenericComposite .

Um cliente moniker (usando um moniker para obter um ponteiro de interface para um objeto) normalmente não precisa saber a classe do moniker ou se é uma composição genérica ou uma composição não genérica; ele pode simplesmente chamar métodos usando um ponteiro de interface IMoniker .

Um provedor de moniker (distribuindo monikers que identificam seus objetos para torná-los acessíveis a clientes moniker) pode precisar compor dois monikers juntos. (Por exemplo, se você estiver usando um moniker de item para identificar um objeto, deverá compor com o moniker que identifica o contêiner do objeto antes de distribuí-lo.) Use o método IMoniker::ComposeWith para fazer isso, chamando o método no primeiro moniker e passando o segundo moniker como um parâmetro; esse método pode produzir uma composição genérica ou não genérica.

A única vez que você deve criar explicitamente um moniker composto genérico é quando você está escrevendo sua própria classe moniker. Na implementação de IMoniker::ComposeWith, você deve tentar executar uma composição não genérica sempre que possível; se você não puder executar uma composição não genérica e a composição genérica for aceitável, você poderá chamar a função CreateGenericComposite para criar um moniker composto genérico.

Implementação do Moniker de Item

Os monikers de item são usados para identificar objetos dentro de contêineres, como uma parte de um documento, um objeto inserido em um documento composto ou um intervalo de células dentro de uma planilha. Os monikers de item geralmente são usados em combinação com monikers de arquivo; um moniker de arquivo é usado para identificar o contêiner enquanto um moniker de item é usado para identificar o item dentro do contêiner.

Um moniker de item contém uma cadeia de caracteres de texto; essa cadeia de caracteres é usada pelo objeto contêiner para distinguir o item contido das outras. O objeto contêiner deve implementar a interface IOleItemContainer ; essa interface permite que o código moniker de item adquira um ponteiro para um objeto, considerando apenas a cadeia de caracteres que identifica o objeto.

Um cliente moniker (usando um moniker para obter um ponteiro de interface para um objeto) normalmente não precisa conhecer a classe do moniker; ele simplesmente chama métodos usando um ponteiro de interface IMoniker .

Um provedor de moniker (distribuindo monikers que identificam seus objetos para torná-los acessíveis a clientes moniker) deve usar monikers de item se os objetos identificados estiverem contidos em outro objeto e puderem ser identificados individualmente usando uma cadeia de caracteres. Use outro tipo de moniker (por exemplo, monikers de arquivo) para identificar o objeto de contêiner.

Para usar monikers de item, você deve usar a função CreateItemMoniker para criar os monikers. Para permitir que seus objetos sejam carregados quando um moniker de item estiver associado, o contêiner de seus objetos deve implementar a interface IOleItemContainer .

O exemplo mais comum de provedores de moniker são aplicativos COM que dão suporte à vinculação. Se o aplicativo COM der suporte à vinculação a objetos menores que um documento baseado em arquivo, você precisará usar monikers de item. Para um aplicativo de servidor que permite vincular a uma seleção dentro de um documento, use os monikers de item para identificar esses objetos. Para um aplicativo de contêiner que permite a vinculação a objetos inseridos, use os monikers de item para identificar os objetos inseridos.

Implementação do Moniker OBJREF

Os monikers OBJREF representam uma referência a uma instância de objeto em execução em um servidor fora do processo, local ou remotamente. O moniker identifica a instância do objeto e o computador em que o objeto está sendo executado.

Um moniker OBJREF é semelhante de várias maneiras a um moniker de ponteiro, exceto que o objeto em execução está fora do processo. Um cliente pode chamar IMoniker::BindToObject em um moniker OBJREF e usar o ponteiro obtido para acessar o objeto em execução, independentemente de sua localização.

Uma distinção importante de um moniker de ponteiro é que o nome de exibição de um moniker OBJREF pode ser inserido em uma página HTML, e o objeto em execução representado pelo moniker pode ser associado por um script de cliente, applet ou controle ActiveX.

O principal uso para um moniker OBJREF é obter acesso a uma instância de objeto em execução pela Internet. Uma página do servidor ativo ou algum outro meio de gerar conteúdo HTML dinâmico coloca o nome de exibição de um moniker OBJREF em um parâmetro para um applet ou um controle ActiveX. O código do applet ou controle chama a função CreateObjrefMoniker para criar um moniker OBJREF com base no nome de exibição e, em seguida, chama IMoniker::BindToObject no moniker OBJREF resultante para obter acesso à instância de objeto em execução. Em seguida, a página do servidor ativo faz marshaling de um ponteiro para o objeto em execução de volta para o cliente da página.

Implementação do Moniker de Ponteiro

Um moniker de ponteiro essencialmente encapsula um ponteiro de interface para que ele se pareça com um moniker e possa ser passado para essas interfaces que exigem monikers. A associação de um moniker de ponteiro é feita chamando o método QueryInterface do ponteiro.

Instâncias de monikers de ponteiro se recusam a ser serializadas; ou seja, IPersistStream::Save retornará um erro. No entanto, esses monikers podem ser realizados em marshaling para um processo diferente em uma chamada RPC; internamente, o sistema realiza marshals e desmarca o ponteiro usando o paradigma padrão para marshaling de ponteiros de interface.

Monikers de ponteiro raramente são necessários. Use monikers de ponteiro somente se precisar de monikers para identificar objetos que não têm representação persistente. Os monikers de ponteiro permitem que esses objetos participem de uma operação de associação de moniker.

Implementação do Moniker de URL

A implementação do moniker de URL do IMoniker é encontrada em um objeto moniker de URL, que também dá suporte a IUnknown e à interface IAsyncMoniker . A interface IMoniker herda sua definição de IPersistStream , bem como IUnknown, e IPersistStream herda do IPersist. Portanto, a implementação do IMoniker inclui suporte para IPersistStream e IPersist.

A interface IAsyncMoniker é simplesmente IUnknown. (Não há métodos adicionais.) Ele é usado para permitir que os clientes determinem se um moniker dá suporte à associação assíncrona.

Para obter um ponteiro para a interface IMoniker nesse objeto, chame a função CreateURLMonikerEx .

Um cliente moniker (usando um moniker para obter um ponteiro de interface para um objeto) normalmente não precisa saber a classe do moniker que está usando; ele simplesmente chama métodos usando um ponteiro de interface IMoniker .

Um provedor de moniker (distribuindo monikers que identificam seus objetos para torná-los acessíveis a clientes moniker) deve usar monikers de item se os objetos que ele identifica estiverem contidos em outro objeto e puderem ser identificados individualmente usando uma cadeia de caracteres. Ele também precisará usar outro tipo de moniker (por exemplo, monikers de arquivo) para identificar o objeto de contêiner.

O exemplo mais comum de provedores de moniker são aplicativos COM que dão suporte à vinculação. Se o aplicativo COM der suporte à vinculação a objetos menores que documentos baseados em arquivo, você precisará usar monikers de item. Para um aplicativo de servidor que permite vincular a uma seleção dentro de um documento, use os monikers de item para identificar esses objetos. Para um aplicativo de contêiner que permite a vinculação a objetos inseridos, use os monikers de item para identificar os objetos inseridos.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows 2000 Server [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	objidl.h