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

  • Artigo

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.

Sintaxe

HRESULT BindToStorage(
  [in]  IBindCtx *pbc,
  [in]  IMoniker *pmkToLeft,
  [in]  REFIID   riid,
  [out] void     **ppvObj
);

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 deste moniker. Esse parâmetro é usado principalmente por implementadores de moniker para habilitar a cooperação entre os vários componentes de um moniker composto. Os clientes Moniker devem usar NULL.

[in] riid

Uma referência ao identificador da interface de armazenamento solicitada, cujo ponteiro será retornado em ppvObj. As interfaces de armazenamento normalmente solicitadas incluem IStorage, IStream e ILockBytes.

[out] ppvObj

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

Retornar valor

Esse método pode retornar os valores de retorno padrão 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_NOSTORAGE
 O objeto identificado por esse moniker não tem seu próprio armazenamento.
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 não pôde se conectar ao armazenamento, possivelmente porque um dispositivo de rede não pôde ser conectado. Para obter mais informações, consulte IMoniker::BindToObject.
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 seu contêiner não oferecer 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

Há uma diferença importante entre os métodos BindToObject e BindToStorage . Se, por exemplo, você tiver um moniker que identifica um objeto de planilha, chamar BindToObject fornecerá acesso ao próprio objeto de planilha, enquanto chamar BindToStorage fornecerá acesso ao objeto de armazenamento no qual reside a planilha.

Anotações para chamadores

Embora nenhuma das classes de moniker COM chame esse método em suas operações de associação, pode ser apropriado chamá-lo na implementação de uma nova classe moniker. Você pode chamar esse método em uma implementação de BindToObject que requer informações do objeto identificado pelo parâmetro pmkToLeft e pode obtê-lo do armazenamento persistente do objeto sem ativação. Por exemplo, se seus monikers forem usados para identificar objetos que podem ser ativados sem ativar seus contêineres, você poderá achar esse método útil.

Um cliente que pode ler o armazenamento do objeto que seu moniker identifica também pode chamar esse método.

Anotações aos implementadores

Sua implementação deve localizar o armazenamento persistente para o objeto identificado pelo moniker atual e retornar o ponteiro de interface desejado. Alguns tipos de monikers representam pseudo-objetos, que são objetos que não têm seu próprio armazenamento persistente. Esses objetos compõem parte do estado interno de seu contêiner, por exemplo, um intervalo de células em uma planilha. Se a classe moniker identificar esse tipo de objeto, a implementação de BindToStorage deverá retornar o erro MK_E_NOSTORAGE.

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 ppvObj (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 Esse método retorna E_NOTIMPL.
Moniker de classe Esse método encaminha para BindToObject do moniker de classe.
Moniker de arquivo Esse método abre o arquivo especificado pelo caminho representado pelo moniker e retorna um ponteiro IStorage para esse arquivo. O método dá suporte apenas à associação à interface IStorage ; se IStream ou ILockBytes for solicitado em riid, o método retornará E_UNSPEC e, se outras interfaces forem solicitadas, esse método retornará E_NOINTERFACE. A menos que pmkToLeft seja um moniker de classe, pmkToLeft deve ser NULL, como na implementação de IMoniker::BindToObject.
Moniker composto genérico Esse método chama BindToStorage 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á IMoniker::BindToObject no parâmetro pmkToLeft , solicitando um ponteiro de interface IOleItemContainer . Em seguida, o método chama IOleItemContainer::GetObjectStorage para a interface solicitada.
Moniker OBJREF Esse método obtém um ponteiro marshaled para a interface solicitada no armazenamento que contém o objeto em execução. 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, BindToStorage falhará com E_UNEXPECTED.
Moniker de ponteiro Esse método consulta o ponteiro encapsulado para a interface solicitada.
Moniker de URL A implementação do sistema de monikers de URL dá suporte a BindToStorage para objetos de fluxo em todas as URLs e para objetos de armazenamento no caso em que o recurso designado é um arquivo composto.

Como o moniker de URL dá suporte à associação assíncrona, o valor de retorno real de bindToStorage pode variar dependendo dos parâmetros de objeto estabelecidos no contexto de associação. No entanto, a semântica da operação de associação é idêntica, independentemente do uso síncrono ou assíncrono, da seguinte maneira:

  • 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 consulta o cliente chamando IBindStatusCallback::GetBindInfo e inicia a operação de associação com o transporte e passa o IBinding resultante para o cliente chamando IBindStatusCallback::OnStartBinding.
  • Se o chamador solicitou um IStream ou IStorage assíncrono especificando o sinalizador BINDF_ASYNCSTORAGE na estrutura BINDINFO recuperada do IBindStatusCallback::GetBindInfo, o moniker de URL retornará o objeto assim que possível. Chamadas para esses objetos IStorage ou IStream que referenciam dados ainda não disponíveis retornam E_PENDING.
  • Se o chamador não especificar IStream ou IStorage assíncrono conforme descrito acima, o moniker de URL ainda retornará um objeto por meio do método IBindStatusCallback::OnDataAvailable assim que possível. No entanto, as chamadas para esses objetos que referenciam dados ainda não disponíveis serão bloqueadas até que os dados fiquem disponíveis. Para alguns aplicativos, isso exigirá a menor modificação de seu código de E/S existente, mas ainda pode resultar em melhor desempenho, dependendo de seus padrões de acesso.

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

Imoniker