Método IBindCtx::RegisterObjectParam (objidl.h)

  • Artigo

Associa um objeto a uma chave de cadeia de caracteres na tabela de ponteiros com chave de cadeia de caracteres do contexto de associação.

Sintaxe

HRESULT RegisterObjectParam(
  [in] LPOLESTR pszKey,
  [in] IUnknown *punk
);

Parâmetros

[in] pszKey

A chave de cadeia de caracteres de contexto de associação sob a qual o objeto está sendo registrado. A comparação de cadeia de caracteres de chave diferencia maiúsculas de minúsculas.

[in] punk

Um ponteiro para a interface IUnknown no objeto que deve ser registrado.

O método chama AddRef no ponteiro.

Retornar valor

Esse método pode retornar os valores de retorno padrão E_OUTOFMEMORY e S_OK.

Comentários

Um contexto de associação mantém uma tabela de ponteiros de interface, cada um associado a uma chave de cadeia de caracteres. Isso permite a comunicação entre uma implementação de moniker e o chamador que iniciou a operação de associação. Uma parte pode armazenar um ponteiro de interface sob uma cadeia de caracteres conhecida por ambas as partes para que a outra parte possa recuperá-la posteriormente do contexto de associação.

As operações de associação subsequentes ao uso desse método podem usar IBindCtx::GetObjectParam para recuperar o ponteiro armazenado.

Anotações para chamadores

RegisterObjectParam é útil para aqueles que implementam uma nova classe moniker (por meio de uma implementação de IMoniker) e para clientes moniker (aqueles que usam monikers para associar a objetos).

Ao implementar uma nova classe moniker, você chama esse método quando ocorre um erro durante a associação de moniker para informar o chamador sobre a causa do erro. A chave que você obteria com uma chamada para esse método dependeria da condição de erro. A seguir está uma lista de erros comuns de associação de moniker, descrevendo para cada uma as chaves que seriam apropriadas:

  • MK_E_EXCEEDEDDEADLINE: se uma operação de associação exceder o prazo porque um determinado objeto não está em execução, registre o moniker do objeto usando a primeira chave não usada da lista: "ExceededDeadline", "ExceededDeadline1", "ExceededDeadline2" e assim por diante. Se o chamador encontrar posteriormente o moniker na tabela de objetos em execução, o chamador poderá repetir a operação de associação.
  • MK_E_CONNECTMANUALLY: a chave "ConnectManually" indica um moniker cuja associação requer assistência do usuário final. Para solicitar que o usuário final se conecte manualmente ao objeto , o chamador pode repetir a operação de associação depois de mostrar o nome de exibição do moniker. Os motivos comuns para esse erro são que uma senha é necessária ou que um disquete precisa ser montado.
  • E_CLASSNOTFOUND: a chave "ClassNotFound" indica um moniker cuja classe não pôde ser encontrada. (O servidor para o objeto identificado por este moniker não pôde ser localizado.) Se essa chave for usada para um objeto de documento composto OLE, o chamador poderá usar IMoniker::BindToStorage para associar ao objeto e, em seguida, tentar executar uma operação Treat As... ou Convert To... para associar o objeto a um servidor diferente. Se isso for bem-sucedido, o chamador poderá repetir a operação de associação.
Um cliente moniker com conhecimento detalhado da implementação do moniker também pode chamar esse método para passar informações privadas para essa implementação.

Você pode definir novas cadeias de caracteres como chaves para armazenar ponteiros. Por convenção, você deve usar nomes de chave que começam com a forma de cadeia de caracteres do CLSID da classe moniker. (Consulte a função StringFromCLSID .)

Se o parâmetro pszKey corresponder ao nome de uma chave existente na tabela do contexto de associação, o novo objeto substituirá o objeto existente na tabela.

Quando você registra um objeto usando esse método, o objeto não é liberado até que ocorra um destes procedimentos:

  • Ele é substituído na tabela por outro objeto com a mesma chave.
  • Ele é removido da tabela por uma chamada para IBindCtx::RevokeObjectParam.
  • O contexto de associação é liberado. Todos os objetos registrados são liberados quando o contexto de associação é liberado.

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

Confira também

Ibindctx