IMoniker::BindToObject

9/8/2008

Este método vincula ao objeto nomeado pelo moniker.

Syntax

HRESULT BindToObject( 
  IBindCtx* pbc, 
  IMoniker* pmkToLeft, 
  REFIID riidResult, 
  void** ppvResult
);

Parameters

• pbc
  [no] Ponteiro para o IBindCtx interface no objeto de contexto BIND, que é usado na operação ligação. O contexto BIND caches objetos ligado durante o processo ligação, contém os parâmetros que aplicar a todas as operações usando o contexto BIND e fornece os meios pelos quais a implementação moniker deve recuperar informações sobre seu ambiente.

• pmkToLeft
  [no] Se o moniker for parte de uma composição moniker, ponteiro para o moniker à esquerda deste moniker. Este parâmetro é usado principalmente pelos implementadores moniker para habilitar cooperação entre os vários componentes de uma composição moniker. Clientes moniker devem transmitir NULL.

• riidResult
  [no] Referência para o identificador da interface de cliente deseja usar para se comunicar com o objeto que identifica o moniker.

• ppvResult
  [out] Endereço da variável de ponteiro que recebe o ponteiro interface solicitado no riid.

  Após bem-sucedido retornar *ppvResult Contém o ponteiro para o objeto que identifica o moniker interface solicitada. Quando bem-sucedido, a implementação deve chamar o IUnknown::AddRef método no moniker.

  É responsabilidade do chamador para o objeto com um chamar versão para o IUnknown::Release método.

  Se ocorrer um erro *ppvResult deve ser NULL.

Return Value

O método suporta o padrão retornam valores, E_UNEXPECTED e E_OUTOFMEMORY. A seguinte tabela mostra os adicionais retornam valores para este método.

Valor	Descrição
S_OK	A operação ligação foi bem-sucedido.
MK_E_NOOBJECT	O objeto identificado por este moniker, ou algum objeto identificado pela composição do qual este moniker é uma parte, moniker não pôde ser encontrado.
MK_E_EXCEEDEDDEADLINE	A operação ligação não pôde ser concluída no limite de tempo especificado do contexto de BIND BIND_OPTS estrutura.
MK_E_CONNECTMANUALLY	A operação ligação requer assistência a partir de usuário final. The most comum razões para retornar esse valor são que uma senha é necessária ou que um disquete precisa ser montado. Quando esse valor é retornado, recuperar o moniker que causou o erro com um chamar para o IBindCtx::GetObjectParam método com a chave "ConnectManually". Você pode, em seguida, chamar o IMoniker::GetDisplayName método para get o nome exibir, exibir um caixa de diálogo que se comunica as informações desejadas, such as instruções para montar um disquete ou uma solicitação para uma senha e, em seguida, repetir a operação ligação.
MK_E_INTERMEDIATEINTERFACENOTSUPPORTED	Um intermediário objeto foi encontrado, mas ele não suporte uma interface exigido para a operação ligação completo. De exemplo, um moniker item retornará esse valor se seu contêiner não suporte a IOleItemContainer interface.
STG_E_ACCESSDENIED	Não é possível acessar o objeto armazenamento.
IOleItemContainer::GetObject Erros	Se o moniker usado para BIND para um objeto contém um item moniker, erros associado com esse método pode ser retornado.

Remarks

IMoniker::BindToObject Implementa o primário de um moniker, que é a função localizar o objeto identificado pelo moniker e retornar um ponteiro para uma das suas interfaces.

Para determinar se a plataforma oferece suporte a esta interface, consulte Determinando suporte COM APIs.

Notas para chamadores

Se você estiver usando um moniker como uma conexão persistente entre dois objetos, você ativar a conexão por chamado IMoniker::BindToObject.

Você geralmente chamar IMoniker::BindToObject Durante o seguinte processo:

1. Criar um objeto contexto BIND com um chamar para o CreateBindCtx função.
2. Chamar IMoniker::BindToObject Usando o moniker, recuperando um ponteiro para uma interface desejado no objeto identificado.
3. Solte o contexto BIND.
4. Por meio de ponteiro interface adquirida, executar as operações sobre o objeto desejadas.
5. Quando terminar com o objeto, versão interface ponteiro do objeto.

O seguinte mostra exemplo de código como completo essas etapas.

// pMnk is an IMoniker * that points to a previously acquired moniker 
// ICellRange is a custom interface designed for an object that is a 
//            range of spreadsheet cells 
ICellRange *pCellRange; 
IBindCtx *pbc; 
 
CreateBindCtx( 0, &pbc ); 
pMnk->BindToObject( pbc, NULL, IID_ICellRange, &pCellRange ); 
pbc->Release(); 
// pCellRange now points to the object; safe to use pCellRange 
pCellRange->Release(); 

Você também pode usar o BindMoniker função quando você pretende uma operação ligação apenas e não precisa reter o objeto contexto BIND. Essa função auxiliar encapsula a criação de contexto de BIND, chamado IMoniker::BindToObjecte liberar o contexto BIND.

Recipientes COM que links suporte aos objetos usam identificadores de origem para localizar e acessar get para o objeto vinculado, mas geralmente não chamar IMoniker::BindToObject diretamente.

Em vez disso, quando um usuário ativa um link em um contêiner, o contêiner link geralmente chamadas de IOleObject Usando implementação do manipulador link, que chama, método IMoniker::BindToObject Sobre o moniker armazenado no objeto vinculado (se ele não é possível identificador o verbo).

Notas para Implementers

O que faz sua implementação depende se você espera o moniker ter um prefixo, that is, se você espera que o pmkToLeft parâmetro seja NULL ou não.

De exemplo, um item moniker, que identifica um objeto em um contêiner, espera que pmkToLeft Identifica o contêiner. Moniker um item, conseqüentemente, usa pmkToLeft Para serviços solicitação a partir desse contêiner.

Se você espera que o moniker ter um prefixo, você deve usar o pmkToLeft parâmetro (de instância, chamado IMoniker::BindToObject nele) para serviços solicitação a partir de objeto ele identifica.

Se você espera que o moniker ter nenhum prefixo, seu IMoniker::BindToObject implementação deve primeiro verificar a Running Object Table (ROT) para verificar se o objeto é já execução.

Para adquirir um ponteiro para o ROT, sua implementação deve chamar o IBindCtx::GetRunningObjectTable método na pbc parâmetro.

Você pode, em seguida, chamar o IRunningObjectTable::GetObject método para verificar se o atual moniker foi registrado na ROT. Se assim, você puder imediatamente chamar o IUnknown::QueryInterface método para get um ponteiro para a interface solicitada pelo chamador.

Requirements

Header	objidl.h, objidl.idl
Library	ole32.lib, uuid.lib
Windows Embedded CE	Windows CE 2.0 and later
Windows Mobile	Windows Mobile Version 5.0 and later

See Also

Reference

BindMoniker
CreateBindCtx
IMoniker::GetDisplayName
IOleObject::DoVerb
IUnknown::AddRef
IUnknown::Release
BIND_OPTS