Metodo IMoniker::ComposeWith (objidl.h)

Crea un nuovo moniker composito combinando il moniker corrente con il moniker specificato.

Sintassi

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

Parametri

[in] pmkRight

Puntatore all'interfaccia IMoniker sul moniker da comporre alla fine di questo moniker.

[in] fOnlyIfNotGeneric

Se TRUE, il chiamante richiede una composizione nongenerica, quindi l'operazione deve procedere solo se pmkRight è una classe moniker che questo moniker può comporre con in qualche modo diverso dalla forma di un composito generico. Se FALSE, il metodo può creare un composito generico se necessario. La maggior parte dei chiamanti deve impostare questo parametro su FALSE.

[out] ppmkComposite

Puntatore a una variabile puntatore IMoniker che riceve il puntatore del moniker composito. In caso di esito positivo, l'implementazione deve chiamare AddRef nel moniker risultante; è responsabilità del chiamante chiamare Release. Se si verifica un errore o se il monikers compose in nulla (ad esempio, la composizione di un moniker anti-moniker con un moniker di elemento o un moniker di file), *ppmkComposite deve essere impostato su NULL.

Valore restituito

Questo metodo può restituire i valori restituiti standard E_OUTOFMEMORY e E_UNEXPECTED, nonché i valori seguenti.

Codice restituito	Descrizione
S_OK	I moniker sono stati combinati correttamente.
MK_E_NEEDGENERIC	Indica che fOnlyIfNotGeneric era TRUE, ma i moniker non potevano essere composti insieme senza creare un moniker composito generico.

Commenti

L'unione di due moniker insieme è denominata composizione. A volte due moniker della stessa classe possono essere combinati in ciò che è chiamato composizione nongenerica. Ad esempio, un moniker di file che rappresenta un percorso incompleto e un altro moniker di file che rappresenta un percorso relativo può essere combinato per formare un singolo moniker di file che rappresenta il percorso completo. La composizione nongenerica per una determinata classe moniker può essere gestita solo nell'implementazione di ComposeWith per tale classe moniker.

La combinazione di due moniker di qualsiasi classe è denominata composizione generica, che può essere eseguita tramite una chiamata alla funzione CreateGenericComposite .

La composizione dei monikers è un'operazione associativa. Vale a dire, se A, B e C sono moniker, dove Comp() rappresenta l'operazione di composizione, Comp( Comp( A, B ), C )

è sempre uguale a Comp( A, Comp( B, C ) ).

Note ai chiamanti

Per combinare due moniker, è consigliabile chiamare ComposeWith anziché chiamare la funzione CreateGenericComposite per dare al primo moniker una possibilità di eseguire una composizione nongenerica.

Oggetto che fornisce moniker di elementi per identificare i relativi oggetti chiamerebbe ComposeWith per fornire un moniker che identifica completamente la posizione dell'oggetto. Ciò si applica, ad esempio, a un server che supporta il collegamento a parti di un documento o a un contenitore che supporta il collegamento a oggetti incorporati all'interno dei relativi documenti. In tale situazione, eseguire le operazioni seguenti:

1. Creare un moniker di elemento che identifica l'oggetto.
2. Ottenere un moniker che identifica il contenitore dell'oggetto.
3. Chiamare ComposeWith nel moniker che identifica il contenitore, passando il moniker dell'elemento come parametro pmkRight .

Note per gli implementatori

È possibile usare la composizione nongenerica o generica per comporre il moniker corrente con il moniker a cui punta pmkRight. Se la classe del moniker indicato da pmkRight è uguale a quella del moniker corrente, è possibile usare il contenuto di pmkRight per eseguire una composizione nongenerica più intelligente.

Nella scrittura di una nuova classe moniker, è necessario decidere se esistono tipi di moniker, sia della propria classe che di un'altra classe, a cui si vuole dare un trattamento speciale. In tal caso, implementare ComposeWith per verificare se pmkRight è un moniker del tipo che deve avere questo trattamento. A tale scopo, è possibile chiamare il metodo IPersist::GetClassID del moniker o se è stato definito un oggetto moniker che supporta un'interfaccia personalizzata, è possibile chiamare QueryInterface nel moniker per tale interfaccia. Un esempio di trattamento speciale sarebbe la composizione nongenerica di un moniker di file assoluto con un moniker di file relativo. Il caso più comune di un moniker speciale è l'inverso per la classe moniker (qualsiasi cosa restituita dall'implementazione di IMoniker::Inverse).

Se pmkRight nega completamente il ricevitore in modo che il composito risultante sia vuoto, è necessario passare NULL in ppmkComposite e restituire il codice di stato S_OK.

Se il parametro pmkRight non è di una classe a cui si concede un trattamento speciale, esaminare fOnlyIfNotGeneric per determinare cosa fare successivamente. Se fOnlyIfNotGeneric è TRUE, passare NULL tramite ppmkComposite e restituire il codice di stato MK_E_NEEDGENERIC. Se fOnlyIfNotGeneric è FALSE, chiamare la funzione CreateGenericComposite per eseguire la composizione in modo generico.

Note specifiche dell'implementazione

Implementazione	Note
Anti-moniker	Se fOnlyIfNotGeneric è TRUE, questo metodo imposta ppmkCompositesu null moniker e restituisce MK_E_NEEDGENERIC; in caso contrario, il metodo restituisce il risultato della combinazione dei due moniker in un composito generico. Si noti che la composizione di un file, un elemento o un moniker puntatore a destra di un anti-moniker produce un composito generico anziché comporre nulla, come sarebbe il caso se l'ordine di composizione fosse invertito.
Moniker classe	Segue il contratto e si comporta come un moniker dell'elemento in che può restituire E_INVALIDARG e MK_E_NEEDGENERIC e così via.
Moniker file	Se pmkRight è un anti-moniker, il moniker restituito è NULL. Se pmkRight è un componente composito il cui componente più sinistro è un moniker anti-moniker, il moniker restituito è il composito con l'anti-moniker più a sinistra rimosso. Se pmkRight è un moniker di file, questo metodo comprime i due moniker in un singolo moniker di file, se possibile. Se non è possibile (ad esempio, se entrambi i moniker di file rappresentano percorsi assoluti, come in d:\work e:\reports), il moniker restituito è NULL e il valore restituito è MK_E_SYNTAX. Se pmkRight non è né un moniker anti-moniker né un moniker di file, il metodo controlla il parametro fOnlyIfNotGeneric ; se è FALSE, il metodo combina i due moniker in un composito generico; se è TRUE, il metodo imposta *ppmkComposite su NULL e restituisce MK_E_NEEDGENERIC.
Moniker composito generico	Se fOnlyIfNotGeneric è TRUE, questo metodo imposta *pmkComposite su NULL e restituisce MK_E_NEEDGENERIC; in caso contrario, il metodo restituisce il risultato della combinazione dei due moniker chiamando la funzione CreateGenericComposite .
Moniker elemento	Se pmkRight è un anti-moniker, il moniker restituito è NULL. Se pmkRight è un componente composito il cui componente più sinistro è un anti-moniker, il moniker restituito è il composito dopo la rimozione dell'anti-moniker più a sinistra. Se pmkRight non è un anti-moniker, il metodo combina i due moniker in un composito generico se fOnlyIfNotGeneric è FALSE; se fOnlyIfNotGeneric è TRUE, il metodo restituisce un moniker NULL e un valore restituito di MK_E_NEEDGENERIC.
Moniker OBJREF	Se pmkRight è un anti-moniker, il moniker restituito è NULL. Se pmkRight è un componente composito il cui componente più sinistro è un moniker anti-moniker, il moniker restituito è il composito con l'anti-moniker più a sinistra rimosso. Se pmkRight non è né un moniker anti-moniker né un moniker composito il cui componente più sinistro è un anti-moniker, il metodo controlla il parametro fOnlyIfNotGeneric . Se è FALSE, il metodo combina i due moniker in un composito generico; se è TRUE, il metodo imposta *ppmkComposite su NULL e restituisce MK_E_NEEDGENERIC.
Moniker puntatore	Se pmkRight è un anti-moniker, il moniker restituito è NULL. Se pmkRight è un componente composito il cui componente più sinistro è un anti-moniker, il moniker restituito è il composito dopo la rimozione dell'anti-moniker più a sinistra. Se fOnlyIfNotGeneric è FALSE, il moniker restituito è un composito generico dei due moniker; in caso contrario, il metodo imposta *ppmkComposite su NULL e restituisce MK_E_NEEDGENERIC.
Moniker URL	I moniker URL supportano la composizione di due URL: un URL di base composto da un URL relativo. Questa composizione viene eseguita in base all'RFC sugli URL relativi. Se fOnlyIfNotGeneric è TRUE, il metodo restituisce MK_E_NEEDGENERIC. In caso contrario, questo metodo restituisce semplicemente CreateGenericComposite(this, pmkRight, ppmkComposite).

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	objidl.h

Vedi anche

CreateGenericComposite

Imoniker