Função CreateBindCtx (objbase.h)

Retorna um ponteiro para uma implementação de IBindCtx (um objeto de contexto de associação). Esse objeto armazena informações sobre uma operação de associação de moniker específica.

Sintaxe

HRESULT CreateBindCtx(
  [in]  DWORD reserved,
  [out] LPBC  *ppbc
);

Parâmetros

[in] reserved

Esse parâmetro é reservado e deve ser 0.

[out] ppbc

Endereço de uma variável de ponteiro IBindCtx* que recebe o ponteiro de interface para o novo objeto de contexto de associação. Quando a função é bem-sucedida, o chamador é responsável por chamar Release no contexto de associação. Um valor NULL para o contexto de associação indica que ocorreu um erro.

Retornar valor

Essa função pode retornar os valores retornados padrão E_OUTOFMEMORY e S_OK.

Comentários

CreateBindCtx é mais comumente usado no processo de associação de um moniker (localizando e obtendo um ponteiro para uma interface identificando-o por meio de um moniker), como nas seguintes etapas:

1. Obtenha um ponteiro para um contexto de associação chamando a função CreateBindCtx .
2. Chame o método IMoniker::BindToObject no moniker, recuperando um ponteiro de interface para o objeto ao qual o moniker se refere.
3. Libere o contexto de associação.
4. Use o ponteiro da interface.
5. Solte o ponteiro da interface.

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

// pMnk is an IMoniker * that points to a previously acquired moniker 
IInterface *pInterface; 
IBindCtx *pbc; 
 
CreateBindCtx( 0, &pbc ); 
pMnk->BindToObject( pbc, NULL, IID_IInterface, &pInterface ); 
pbc->Release(); 

// pInterface now points to the object; safe to use pInterface 
pInterface->Release(); 

Contextos de associação também são usados em outros métodos da interface IMoniker além de IMoniker::BindToObject e na função MkParseDisplayName .

Um contexto de associação retém referências aos objetos associados durante a operação de associação, fazendo com que os objetos associados permaneçam ativos (mantendo o servidor do objeto em execução) até que o contexto de associação seja liberado. Reutilização de um contexto de associação quando operações subsequentes são associadas ao mesmo objeto pode melhorar o desempenho. No entanto, você deve liberar o contexto de associação assim que possível, pois pode manter os objetos ativados desnecessariamente.

Um contexto de associação contém uma estrutura BIND_OPTS , que contém parâmetros que se aplicam a todas as etapas em uma operação de associação. Quando você cria um contexto de associação usando CreateBindCtx, os campos da estrutura BIND_OPTS são inicializados da seguinte maneira.

cbStruct = sizeof(BIND_OPTS) 
grfFlags = 0 
grfMode = STGM_READWRITE 
dwTickCountDeadline = 0

Você pode chamar o método IBindCtx::SetBindOptions para modificar esses valores padrão.

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	objbase.h
Biblioteca	Ole32.lib
DLL	Ole32.dll

Confira também

Ibindctx

Imoniker

Mkparsedisplayname