Método IMoniker::BindToObject (objidl.h)

Artigo
08/25/2023

Associa ao objeto especificado. O processo de associação envolve localizar 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.

Sintaxe

HRESULT BindToObject(
  [in]  IBindCtx *pbc,
  [in]  IMoniker *pmkToLeft,
  [in]  REFIID   riidResult,
  [out] void     **ppvResult
);

Parâmetros

[in] pbc

Um ponteiro para a interface IBindCtx no objeto de contexto de associação, que é usado nesta operação de associação. O contexto de associação armazena em cache objetos associados durante o processo de associação, contém parâmetros que se aplicam a todas as operações usando o contexto de associação e fornece os meios pelos quais a implementação do moniker deve recuperar informações sobre seu ambiente.

[in] pmkToLeft

Se o moniker fizer parte de um moniker composto, ponteiro para o moniker à esquerda desse moniker. Esse parâmetro é usado principalmente por implementadores de moniker para permitir a cooperação entre os vários componentes de um moniker composto. Os clientes moniker devem usar NULL.

[in] riidResult

O IID da interface que o cliente deseja usar para se comunicar com o objeto que o moniker identifica.

[out] ppvResult

O endereço da variável de ponteiro que recebe o ponteiro de interface solicitado em riid. Após o retorno bem-sucedido, *ppvResult contém o ponteiro de interface solicitado para o objeto que o moniker identifica. Quando bem-sucedida, a implementação deve chamar AddRef no moniker. É responsabilidade do chamador chamar Release. Se ocorrer um erro, *ppvResult deverá ser NULL.

Retornar valor

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

Código de retorno	Descrição
S_OK	A operação de associação foi bem-sucedida.
MK_E_NOOBJECT	Não foi possível encontrar o objeto identificado por esse moniker ou algum objeto identificado pelo moniker composto do qual esse moniker faz parte.
MK_E_EXCEEDEDDEADLINE	A operação de associação não pôde ser concluída dentro do limite de tempo especificado pela estrutura de BIND_OPTS do contexto de associação.
MK_E_CONNECTMANUALLY	A operação de associação requer assistência do usuário final. O motivo mais comum para retornar esse valor é que uma senha é necessária ou que um disquete precisa ser montado. Quando esse valor for retornado, recupere o moniker que causou o erro com uma chamada para IBindCtx::GetObjectParam com a chave "ConnectManually". Em seguida, você pode chamar IMoniker::GetDisplayName para obter o nome de exibição, exibir uma caixa de diálogo que comunique as informações desejadas, como instruções para montar um disquete ou uma solicitação de uma senha e tentar novamente a operação de associação.
MK_E_INTERMEDIATEINTERFACENOTSUPPORTED	Um objeto intermediário foi encontrado, mas não deu suporte a uma interface necessária para concluir a operação de associação. Por exemplo, um moniker de item retornará esse valor se o contêiner não der suporte à interface IOleItemContainer .
STG_E_ACCESSDENIED	Não é possível acessar o objeto de armazenamento.

Esse método também pode retornar os erros associados ao método IOleItemContainer::GetObject .

Comentários

BindToObject implementa a função primária de um moniker, que é localizar o objeto identificado pelo moniker e retornar um ponteiro para uma de suas interfaces.

Anotações aos Chamadores

Se você estiver usando um moniker como uma conexão persistente entre dois objetos, ative a conexão chamando BindToObject.

Normalmente, você chama BindToObject durante o seguinte processo:

Crie um objeto de contexto de associação com uma chamada para a função CreateBindCtx .
Chame BindToObject usando o moniker, recuperando um ponteiro para uma interface desejada no objeto identificado.
Libere o contexto de associação.
Por meio do ponteiro de interface adquirido, execute as operações desejadas no objeto .
Quando terminar com o objeto , libere o ponteiro da interface do objeto.

O fragmento de código a seguir ilustra essas etapas.

HRESULT hr;       // An error code
IMoniker * pMnk;  // A previously acquired interface moniker

// Obtain an IBindCtx interface.
IBindCtx * pbc; 
hr = CreateBindCtx(NULL, &amp;pbc); 
if (FAILED(hr)) exit(0);  // Handle errors here. 
   
// Obtain an implementation of pCellRange. 
ICellRange * pCellRange; 
hr = pMnk-&gt;BindToObject(pbc, NULL, IID_ICellRange, &amp;pCellRange); 
if (FAILED(hr)) exit(0);  // Handle errors here. 

// Use pCellRange here. 

// Release interfaces after use. 
pbc-&gt;Release(); 
pCellRange-&gt;Release();

Você também pode usar a função BindMoniker quando pretende apenas uma operação de associação e não precisa reter o objeto de contexto de associação. Essa função auxiliar encapsula a criação do contexto de associação, chamando BindToObject e liberando o contexto de associação.

Contêineres COM que dão suporte a links para objetos usam monikers para localizar e obter acesso ao objeto vinculado, mas normalmente não chamam BindToObject diretamente. Em vez disso, quando um usuário ativa um link em um contêiner, o contêiner de link geralmente chama IOleObject::D oVerb, usando a implementação do manipulador de link, que chama BindToObject no moniker armazenado no objeto vinculado (se ele não puder manipular o verbo).

Observações aos implementadores

O que sua implementação faz depende se você espera que seu moniker tenha um prefixo; ou seja, se você espera que o parâmetro pmkToLeft seja NULL ou não. Por exemplo, um moniker de item, que identifica um objeto dentro de um contêiner, espera que pmkToLeft identifique o contêiner. Consequentemente, um moniker de item usa pmkToLeft para solicitar serviços desse contêiner. Se você espera que seu moniker tenha um prefixo, use o parâmetro pmkToLeft (por exemplo, chamando BindToObject nele) para solicitar serviços do objeto que ele identifica.

Se você espera que o moniker não tenha nenhum prefixo, a implementação de BindToObject deve primeiro marcar a ROT (tabela de objetos em execução) para ver se o objeto já está em execução. Para adquirir um ponteiro para o ROT, sua implementação deve chamar IBindCtx::GetRunningObjectTable no parâmetro pbc . Em seguida, você pode chamar o método IRunningObjectTable::GetObject para ver se o moniker atual foi registrado no ROT. Nesse caso, você pode chamar QueryInterface imediatamente para obter um ponteiro para a interface solicitada pelo chamador.

Quando a implementação bindToObject se associa a algum objeto, ela deve usar o parâmetro pbc para chamar IBindCtx::RegisterObjectBound para armazenar uma referência ao objeto associado no contexto de associação. Isso garante que o objeto associado permaneça em execução até que o contexto de associação seja liberado, o que pode evitar a despesa de ter uma operação de associação subsequente para carregá-lo novamente mais tarde.

Se a estrutura BIND_OPTS do contexto de associação especificar o sinalizador BINDFLAGS_JUSTTESTEXISTENCE, sua implementação terá a opção de retornar NULL em ppvResult (embora você também possa ignorar o sinalizador e executar a operação de associação completa).

Notas específicas da implementação

Implementação	Observações
Anti-moniker	Este método não está implementado. Ele retorna E_NOTIMPL.
Moniker de classe	Se pmkLeft for NULL, chamará CoGetClassObject, usando o CLSID com o qual o moniker de classe foi inicializado (em CreateClassMoniker ou por meio de MkParseDisplayName) e o CLSCTX do pbc atual (IBindCtx). Se pmkLeft não for NULL, chamará pmkLeft-BindToObject> para IClassActivator e chamará IClassActivator::GetClassObject com o CLSID com o qual foi inicializado e os parâmetros CLSCTX e localidade do pbc atual (IBindCtx).
Moniker de arquivo	Quando pmkToLeft é NULL, o método procura o moniker no ROT e, se encontrado, consulta o objeto recuperado para o ponteiro de interface solicitado. Se o moniker não for encontrado no ROT, o método carregará o objeto do sistema de arquivos e recuperará o ponteiro de interface solicitado. Se pmkLeft não for NULL, em vez de determinar a classe para instanciar e inicializar com o conteúdo do arquivo referenciado pelo moniker de arquivo usando GetClassFile (ou outros meios), chame pmkLeft-BindToObject> para IClassFactory e IClassActivator, recupere esse ponteiro em pcf. Se isso falhar com E_NOINTERFACE, retorne MK_E_INTERMEDIATEINTERFACENOTSUPPORTED. Se o ponteiro IClassFactory for recuperado com êxito, chame pcf-CreateInstance>(IID_IPersistFile, (void**)&ppf) para obter uma nova instância da classe a ser inicializada e inicializá-la usando IPersistFile ou outros meios apropriados de acordo com os caminhos de inicialização existentes do moniker de arquivo.
Moniker composto genérico	Se pmkToLeft for NULL, esse método procurará o moniker no ROT e, se encontrado, consultará o objeto recuperado para o ponteiro de interface solicitado. Se pmkToLeft não for NULL, o método chamará BindToObject recursivamente no componente mais à direita da composição, passando o restante da composição como o parâmetro pmkToLeft para essa chamada.
Moniker de item	Se pmkToLeft for NULL, esse método retornará E_INVALIDARG. Caso contrário, o método chamará BindToObject no parâmetro pmkToLeft , solicitando um ponteiro de interface IOleItemContainer . Em seguida, o método chama IOleItemContainer::GetObject, passando a cadeia de caracteres contida no moniker e retorna o ponteiro de interface solicitado.
Moniker OBJREF	O parâmetro pmkToLeft deve ser NULL. Como o moniker OBJREF representa um objeto em execução, nenhuma ativação ocorre. Se o objeto representado não estiver mais em execução, BindToObject falhará com E_UNEXPECTED.
Moniker de ponteiro	Esse método consulta o ponteiro encapsulado para a interface solicitada.
Moniker de URL	Como o Moniker de URL dá suporte à associação assíncrona, o valor de retorno real de seu BindToObject pode variar dependendo dos parâmetros de objeto estabelecidos no contexto de associação. Para obter mais informações, veja abaixo.

A semântica da operação de associação para um moniker de URL é idêntica, independentemente do uso síncrono ou assíncrono, e são as seguintes:

O moniker de URL extrai mais informações para a operação de associação do contexto de associação. Por exemplo, o moniker pode obter ponteiros para as interfaces IBindStatusCallback e IEnumFORMATETC registradas no contexto de associação. Outras informações podem incluir opções de associação adicionais especificadas no contexto de associação por meio de IBindCtx::SetBindOptions, como o parâmetro dwTickCountDeadline ou o valor grfFlags de BIND_MAYBOTHERUSER.
Em seguida, o moniker verifica a ROT do contexto de associação para determinar se o objeto referenciado já está em execução. O moniker pode obter essas informações com as seguintes chamadas:
```
IBindCtx::GetRunningObjectTable(&amp;prot)
prot-&gt;IsRunning(this)
```
Se o objeto já estiver em execução, o moniker recuperará o objeto em execução com a seguinte chamada:
```
prot-&gt;GetObject(this, &amp;punk)
```
Em seguida, o moniker chama QueryInterface para a interface solicitada.
Caso contrário, o moniker consulta o cliente chamando IBindStatusCallback::GetBindInfo para obter informações adicionais de associação. Em seguida, o moniker inicia a operação de associação e passa a interface IBinding resultante de volta para o cliente chamando IBindStatusCallback::OnStartBinding.
Se na etapa 1 foi determinado que se trata de uma associação assíncrona, BindToObject retorna MK_S_ASYNCHRONOUS neste ponto com NULL em ppv. O chamador receberá o ponteiro de objeto real durante o método IBindStatusCallback::OnObjectAvailable em algum momento posterior. Em seguida, as etapas a seguir ocorrem de forma assíncrona para o chamador, normalmente em outro thread de execução.
A classe do recurso designado pelo Moniker de URL é determinada de uma das seguintes maneiras:
- O moniker de URL examina o tipo de mídia dos dados. Se o tipo de mídia for application/x-oleobject, os primeiros 16 bytes dos dados reais (Content-Body) contêm o CLSID do recurso e os dados subsequentes deverão ser interpretados pela própria classe. Para todos os outros tipos de mídia, o Moniker de URL procura no registro do sistema a chave HKEY_CLASSES_ROOT\MIME\Database\Content-Type\<media-type>\CLSID. Observe que application/x-oleobject será usado até que application/oleobject seja aprovado.
- O moniker de URL corresponde a partes dos dados que chegam aos padrões registrados no registro do sistema em HKEY_CLASSES_ROOT\FileTypes.
- Por fim, se tudo falhar, o Moniker de URL correlacionará a extensão à direita do recurso, se houver, a um CLSID usando o HKEY_CLASSES_ROOT\.??? chaves no registro do sistema, como é feito por GetClassFile e o shell.
Depois de determinar a classe , o moniker de URL cria uma instância usando CoCreateInstance de CLSCTX_SERVER solicitando a interface IUnknown .
Em seguida, o moniker de URL chama o método QueryInterface do objeto recém-criado para a interface IPersistMoniker . Se QueryInterface for bem-sucedido, o moniker de URL chamará IPersistMoniker::Load passando a si mesmo (isso) como o parâmetro moniker. O objeto normalmente chama BindToStorage solicitando a interface de armazenamento na qual eles estão interessados.
Caso contrário, o moniker de URL chama QueryInterface para IPersistStream e, se bem-sucedido, chama IPersistStream::Load, passando o objeto um ponteiro IStream para um objeto de fluxo que está sendo preenchido de forma assíncrona pelo transporte.
Se a classe que está sendo chamada não estiver marcada com a categoria CATID_AsyncAware, chamará ISequentialStream::Read ou ISequentialStream::Write que os dados de referência ainda não estão disponíveis até que os dados fiquem disponíveis. Essas chamadas são bloqueadas no sentido COM tradicional. Um loop de mensagem é inserido, o que permite que determinadas mensagens sejam processadas e o IMessageFilter do thread é chamado adequadamente.

Se a classe estiver marcada com a categoria CATID_AsyncAware, as chamadas para ISequentialStream::Read ou ISequentialStream::Write esses dados de referência ainda não disponíveis retornarão E_PENDING.
Caso contrário, o moniker de URL chamará QueryInterface para IPersistFile e, se tiver êxito, concluirá o download em um arquivo temporário. Após a conclusão, o moniker de URL chama IPersistFile::Load. O arquivo criado é armazenado em cache junto com outros dados baixados pela Internet. O cliente deve ter certeza de não excluir esse arquivo.
Quando o objeto retorna de uma das várias chamadas load descritas nas etapas anteriores, o moniker de URL chama o método IBindStatusCallback::OnObjectAvailable para retornar o ponteiro de interface que o cliente solicitou originalmente quando o cliente chamou BindToObject.

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

BindMoniker

Imoniker

Método IMoniker::BindToObject (objidl.h)

Sintaxe

Parâmetros

Retornar valor

Comentários

Anotações aos Chamadores

Observações aos implementadores

Notas específicas da implementação

Requisitos

Confira também

Comentários

Comentários

Recursos adicionais