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

Cria um novo moniker composto combinando o moniker atual com o moniker especificado.

Sintaxe

HRESULT ComposeWith(
  [in]  IMoniker *pmkRight,
  [in]  BOOL     fOnlyIfNotGeneric,
  [out] IMoniker **ppmkComposite
);

Parâmetros

[in] pmkRight

Um ponteiro para a interface IMoniker no moniker a ser redigido no final deste moniker.

[in] fOnlyIfNotGeneric

Se TRUE, o chamador exigirá uma composição não genérica, portanto, a operação deve continuar somente se pmkRight for uma classe moniker com a qual esse moniker pode compor de alguma forma diferente de formar uma composição genérica. Se FALSE, o método poderá criar uma composição genérica, se necessário. A maioria dos chamadores deve definir esse parâmetro como FALSE.

[out] ppmkComposite

Um ponteiro para uma variável de ponteiro IMoniker que recebe o ponteiro de moniker composto. Quando bem-sucedida, a implementação deve chamar AddRef no moniker resultante; é responsabilidade do chamador chamar Release. Se ocorrer um erro ou se os monikers se redigirem para nada (por exemplo, compondo um anti-moniker com um moniker de item ou um moniker de arquivo), *ppmkComposite deverá ser definido como NULL.

Retornar valor

Esse método pode retornar os valores de retorno padrão E_OUTOFMEMORY e E_UNEXPECTED, bem como os valores a seguir.

Código de retorno	Descrição
S_OK	Os monikers foram combinados com êxito.
MK_E_NEEDGENERIC	Indica que fOnlyIfNotGeneric era TRUE, mas os monikers não podiam ser compostos juntos sem criar um moniker composto genérico.

Comentários

Unir dois monikers é chamado de composição. Às vezes, dois monikers da mesma classe podem ser combinados no que é chamado de composição não genérica. Por exemplo, um moniker de arquivo que representa um caminho incompleto e outro moniker de arquivo que representa um caminho relativo pode ser combinado para formar um único moniker de arquivo que representa o caminho completo. A composição não genérica para uma determinada classe moniker só pode ser tratada na implementação de ComposeWith para essa classe moniker.

A combinação de dois monikers de qualquer classe é chamada de composição genérica, que pode ser realizada por meio de uma chamada para a função CreateGenericComposite .

A composição de monikers é uma operação associativa. Ou seja, se A, B e C forem monikers, então, em que Comp() representa a operação de composição, Comp( Comp( A, B ), C )

é sempre igual a Comp( A, Comp( B, C ) ).

Anotações para chamadores

Para combinar dois monikers, você deve chamar ComposeWith em vez de chamar a função CreateGenericComposite para dar ao primeiro moniker a chance de executar uma composição não genérica.

Um objeto que fornece monikers de item para identificar seus objetos chamaria ComposeWith para fornecer um moniker que identifica completamente o local do objeto. Isso se aplicaria, por exemplo, a um servidor que dá suporte à vinculação a partes de um documento ou a um contêiner que dá suporte à vinculação a objetos inseridos em seus documentos. Em tal situação, você faria o seguinte:

1. Crie um moniker de item que identifique o objeto .
2. Obtenha um moniker que identifica o contêiner do objeto.
3. Chame ComposeWith no moniker que identifica o contêiner, passando o moniker de item como o parâmetro pmkRight .

Anotações aos implementadores

Você pode usar uma composição não genérica ou genérica para compor o moniker atual com o moniker para o qual pmkRight aponta. Se a classe do moniker indicada por pmkRight for igual à do moniker atual, é possível usar o conteúdo de pmkRight para executar uma composição não genérica mais inteligente.

Ao escrever uma nova classe de moniker, você deve decidir se há algum tipo de monikers, seja de sua própria classe ou outra classe, para a qual você deseja dar tratamento especial. Nesse caso, implemente ComposeWith para marcar se pmkRight é um moniker do tipo que deve ter esse tratamento. Para fazer isso, você pode chamar o método IPersist::GetClassID do moniker ou, se tiver definido um objeto moniker que dá suporte a uma interface personalizada, você pode chamar QueryInterface no moniker para essa interface. Um exemplo de tratamento especial seria a composição não genérica de um moniker de arquivo absoluto com um moniker de arquivo relativo. O caso mais comum de um moniker especial é o inverso para sua classe moniker (o que você retornar da implementação de IMoniker::Inverse).

Se pmkRight negar completamente o receptor para que a composição resultante esteja vazia, você deverá retornar NULL em ppmkComposite e retornar o código status S_OK.

Se o parâmetro pmkRight não for de uma classe à qual você fornece tratamento especial, examine fOnlyIfNotGeneric para determinar o que fazer a seguir. Se fOnlyIfNotGeneric for TRUE, passe NULL por ppmkComposite e retorne o código status MK_E_NEEDGENERIC. Se fOnlyIfNotGeneric for FALSE, chame a função CreateGenericComposite para executar a composição genericamente.

Notas específicas da implementação

Implementação	Observações
Anti-moniker	Se fOnlyIfNotGeneric for TRUE, esse método definirá ppmkComposite como moniker NULL e retornará MK_E_NEEDGENERIC; caso contrário, o método retorna o resultado da combinação dos dois monikers em uma composição genérica. Observe que compor um arquivo, item ou moniker de ponteiro à direita de um anti-moniker produz uma composição genérica em vez de compor para nada, como seria o caso se a ordem de composição fosse invertida.
Moniker de classe	Segue o contrato e se comporta como um moniker de item, pois ele pode retornar E_INVALIDARG e MK_E_NEEDGENERIC, e assim por diante.
Moniker de arquivo	Se pmkRight for um anti-moniker, o moniker retornado será NULL. Se pmkRight for uma composição cujo componente mais à esquerda é um anti-moniker, o moniker retornado será a composição com o anti-moniker mais à esquerda removido. Se pmkRight for um moniker de arquivo, esse método recolherá os dois monikers em um único moniker de arquivo, se possível. Se não for possível (por exemplo, se ambos os monikers de arquivo representarem caminhos absolutos, como em d:\work e e:\reports), o moniker retornado será NULL e o valor retornado será MK_E_SYNTAX. Se pmkRight não for um anti-moniker nem um moniker de arquivo, o método verificará o parâmetro fOnlyIfNotGeneric ; se for FALSE, o método combinará os dois monikers em uma composição genérica; se for TRUE, o método definirá *ppmkComposite como NULL e retornará MK_E_NEEDGENERIC.
Moniker composto genérico	Se fOnlyIfNotGeneric for TRUE, esse método definirá *pmkComposite como NULL e retornará MK_E_NEEDGENERIC; caso contrário, o método retorna o resultado da combinação dos dois monikers chamando a função CreateGenericComposite .
Moniker de item	Se pmkRight for um anti-moniker, o moniker retornado será NULL. Se pmkRight for uma composição cujo componente mais à esquerda é um anti-moniker, o moniker retornado será a composição depois que o anti-moniker mais à esquerda for removido. Se pmkRight não for um anti-moniker, o método combinará os dois monikers em uma composição genérica se fOnlyIfNotGeneric for FALSE; se fOnlyIfNotGeneric for TRUE, o método retornará um moniker NULL e um valor retornado de MK_E_NEEDGENERIC.
Moniker OBJREF	Se pmkRight for um anti-moniker, o moniker retornado será NULL. Se pmkRight for uma composição cujo componente mais à esquerda é um anti-moniker, o moniker retornado será a composição com o anti-moniker mais à esquerda removido. Se pmkRight não for um anti-moniker nem um moniker composto cujo componente mais à esquerda é um anti-moniker, o método verifica o parâmetro fOnlyIfNotGeneric . Se for FALSE, o método combinará os dois monikers em uma composição genérica; se for TRUE, o método definirá *ppmkComposite como NULL e retornará MK_E_NEEDGENERIC.
Moniker de ponteiro	Se pmkRight for um anti-moniker, o moniker retornado será NULL. Se pmkRight for uma composição cujo componente mais à esquerda é um anti-moniker, o moniker retornado será a composição depois que o anti-moniker mais à esquerda for removido. Se fOnlyIfNotGeneric for FALSE, o moniker retornado será uma composição genérica dos dois monikers; caso contrário, o método define *ppmkComposite como NULL e retorna MK_E_NEEDGENERIC.
Moniker de URL	Os monikers de URL dão suporte à composição de duas URLs: uma URL base composta por uma URL relativa. Essa composição é feita de acordo com o RFC em URLs relativas. Se fOnlyIfNotGeneric for TRUE, o método retornará MK_E_NEEDGENERIC. Caso contrário, esse método simplesmente retorna CreateGenericComposite(this, pmkRight, ppmkComposite).

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

CreateGenericComposite

Imoniker