Método IOleLink::BindToSource (oleidl.h)

Artigo
08/25/2023

Ativa a conexão com a origem do link associando o moniker armazenado no objeto vinculado.

Sintaxe

HRESULT BindToSource(
  [in] DWORD    bindflags,
  [in] IBindCtx *pbc
);

Parâmetros

[in] bindflags

Especifica como proceder se a origem do link tiver um CLSID diferente da última vez em que foi associada. Se esse parâmetro for zero e os CLSIDs forem diferentes, o método falhará e retornará OLE_E_CLASSDIFF. Se o valor OLELINKBIND_EVENIFCLASSDIFF da enumeração OLELINKBIND for especificado e os CLSIDs forem diferentes, o método será associado com êxito e atualizará o CLSID armazenado no objeto vinculado.

[in] pbc

Um ponteiro para a interface IBindCtx no contexto de associação a ser usado nesta operação de associação. Este parâmetro pode ser NULL. 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 da associação deve recuperar informações sobre seu ambiente. Para obter mais informações, consulte IBindCtx.

Retornar valor

Esse método retorna S_OK em caso de êxito. Outros valores retornados possíveis incluem o seguinte.

Código de retorno	Descrição
OLE_E_CLASSDIFF	A origem do link não foi associada porque seu CLSID foi alterado. Esse erro será retornado somente se o sinalizador OLELINKBIND_EVENIFCLASSDIFF não for especificado no parâmetro bindflags .
MK_E_NOOBJECT	Não foi possível encontrar a origem do link ou (se o moniker da origem do link for uma composição), não foi possível encontrar algum objeto intermediário identificado na composição.
E_UNSPEC	O moniker do link é NULL.

Associar o moniker pode exigir a chamada da função CreateBindCtx ; portanto, esse método pode retornar erros gerados por CreateBindCtx.

Comentários

Anotações aos Chamadores

Normalmente, seu aplicativo de contêiner não precisa chamar o método IOleLink::BindToSource diretamente. Quando é necessário ativar a conexão com a origem do link, seu contêiner normalmente chama IOleObject::D oVerb, IOleObject::Update ou IOleLink::Update. A implementação desses métodos pelo objeto vinculado chama IOleLink::BindToSource. Seu contêiner também pode chamar a função OleRun , que chama IOleLink::BindToSource quando chamado em um objeto vinculado.

Em cada um dos exemplos listados anteriormente, em que IOleLink::BindToSource é chamado indiretamente, o parâmetro bindflags é definido como zero. Consequentemente, essas chamadas poderão falhar com o erro OLE_E_CLASSDIFF se a classe da origem do link for diferente da última vez em que o objeto vinculado foi associado. Isso pode acontecer, por exemplo, se a origem do link original fosse uma planilha inserida do Lotus que um usuário final havia convertido posteriormente (usando a caixa de diálogo Alterar Tipo) em uma planilha do Excel.

Se você quiser que o contêiner se associe mesmo que a origem do link agora tenha um CLSID diferente, chame IOleLink::BindToSource diretamente e especifique OLELINKBIND_EVENIFCLASSDIFF para o parâmetro bindflags. Essa chamada se associa à origem do link e atualiza o CLSID do objeto de link. Como alternativa, o contêiner pode excluir o link existente e usar a função OleCreateLink para criar um novo objeto vinculado.

Observações aos implementadores

O objeto vinculado armazena em cache o ponteiro da interface para a origem do link adquirida durante a associação.

A implementação IOleLink::BindToSource do objeto vinculado primeiro tenta associar usando um moniker que consiste no moniker do documento composto com o moniker relativo da origem do link. Se tiver êxito, ele atualizará o moniker absoluto do link. Caso contrário, ele tentará associar usando o moniker absoluto, atualizando o moniker relativo se tiver êxito.

Se IOleLink::BindToSource se associar à origem do link, ele chamará a implementação IOleContainer::LockContainer do documento composto para manter o documento composto contido ativo enquanto a origem do link está em execução. IOleLink::BindToSource também chama as implementações IOleObject::Advise e IDataObject::D Advise da origem do link para configurar conexões de consultoria. A implementação IOleLink::UnbindSource desbloqueia o contêiner e exclui as conexões de consultoria.

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