IMoniker ::ComposeWith, méthode (objidl.h)

Article
02/29/2024

Crée un moniker composite en combinant le moniker actuel avec le moniker spécifié.

Syntaxe

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

Paramètres

[in] pmkRight

Pointeur vers l’interface IMoniker sur le moniker à composer à la fin de ce moniker.

[in] fOnlyIfNotGeneric

Si la valeur est TRUE, l’appelant nécessite une composition non générique. L’opération doit donc se poursuivre uniquement si pmkRight est une classe moniker avec laquelle ce moniker peut composer d’une manière autre que la formation d’un composite générique. Si la valeur est FALSE, la méthode peut créer un composite générique si nécessaire. La plupart des appelants doivent définir ce paramètre sur FALSE.

[out] ppmkComposite

Pointeur vers une variable pointeur IMoniker qui reçoit le pointeur moniker composite. En cas de réussite, l’implémentation doit appeler AddRef sur le moniker résultant ; il incombe à l’appelant d’appeler Release. Si une erreur se produit ou si les monikers composent à rien (par exemple, la composition d’un anti-moniker avec un moniker d’élément ou un moniker de fichier), *ppmkComposite doit être défini sur NULL.

Valeur retournée

Cette méthode peut retourner les valeurs de retour standard E_OUTOFMEMORY et E_UNEXPECTED, ainsi que les valeurs suivantes.

Code de retour	Description
S_OK	Les monikers ont été combinés avec succès.
MK_E_NEEDGENERIC	Indique que fOnlyIfNotGeneric était TRUE, mais que les monikers n’ont pas pu être composés ensemble sans créer un moniker composite générique.

Remarques

La jonction de deux monikers est appelée composition. Parfois, deux monikers de la même classe peuvent être combinés dans ce qu’on appelle la composition non générique. Par exemple, un moniker de fichier représentant un chemin d’accès incomplet et un autre moniker de fichier représentant un chemin relatif peuvent être combinés pour former un moniker de fichier unique représentant le chemin d’accès complet. La composition non générique pour une classe moniker donnée ne peut être gérée que dans l’implémentation de ComposeWith pour cette classe moniker.

La combinaison de deux monikers d’une classe est appelée composition générique, ce qui peut être accompli par un appel à la fonction CreateGenericComposite .

La composition de monikers est une opération associative. Autrement dit, si A, B et C sont des monikers, alors, où Comp() représente l’opération de composition, Comp( Comp( A, B ), C )

est toujours égal à Comp( A, Comp( B, C ) ).

Remarques aux appelants

Pour combiner deux monikers, vous devez appeler ComposeWith au lieu d’appeler la fonction CreateGenericComposite pour donner au premier moniker la possibilité d’effectuer une composition non générique.

Un objet qui fournit des monikers d’élément pour identifier ses objets appelle ComposeWith pour fournir un moniker qui identifie complètement l’emplacement de l’objet. Cela s’applique, par exemple, à un serveur qui prend en charge la liaison à des parties d’un document, ou à un conteneur qui prend en charge la liaison à des objets incorporés dans ses documents. Dans une telle situation, vous devez effectuer les opérations suivantes :

Créez un moniker d’élément qui identifie l’objet .
Obtenez un moniker qui identifie le conteneur de l’objet.
Appelez ComposeWith sur le moniker en identifiant le conteneur, en passant le moniker d’élément comme paramètre pmkRight .

Remarques aux implémenteurs

Vous pouvez utiliser une composition non générique ou générique pour composer le moniker actuel avec le moniker vers lequel pmkRight pointe. Si la classe du moniker indiquée par pmkRight est identique à celle du moniker actuel, il est possible d’utiliser le contenu de pmkRight pour effectuer une composition non générique plus intelligente.

En écrivant un nouveau cours de moniker, vous devez décider s’il existe des types de monikers, que ce soit de votre propre classe ou d’une autre classe, auxquels vous voulez donner un traitement spécial. Si c’est le cas, implémentez ComposeWith pour case activée si pmkRight est un moniker du type qui doit avoir ce traitement. Pour ce faire, vous pouvez appeler la méthode IPersist ::GetClassID du moniker, ou si vous avez défini un objet moniker qui prend en charge une interface personnalisée, vous pouvez appeler QueryInterface sur le moniker pour cette interface. Un exemple de traitement spécial serait la composition non générique d’un moniker de fichier absolu avec un moniker de fichier relatif. Le cas le plus courant d’un moniker spécial est l’inverse pour votre classe moniker (tout ce que vous retournez de votre implémentation de IMoniker ::Inverse).

Si pmkRight annule complètement le récepteur afin que le composite résultant soit vide, vous devez renvoyer la valeur NULL dans ppmkComposite et retourner le code status S_OK.

Si le paramètre pmkRight ne fait pas partie d’une classe à laquelle vous accordez un traitement spécial, examinez fOnlyIfNotGeneric pour déterminer ce qu’il faut faire ensuite. Si fOnlyIfNotGeneric a la valeur TRUE, transmettez null à ppmkComposite et retournez le code status MK_E_NEEDGENERIC. Si fOnlyIfNotGeneric a la valeur FALSE, appelez la fonction CreateGenericComposite pour effectuer la composition de manière générique.

Notes spécifiques à l’implémentation

Implémentation	Notes
Anti-moniker	Si fOnlyIfNotGeneric a la valeur TRUE, cette méthode affecte à ppmkComposite la valeur NULL moniker et retourne MK_E_NEEDGENERIC ; sinon, la méthode retourne le résultat de la combinaison des deux monikers dans un composite générique. Notez que la composition d’un fichier, d’un élément ou d’un moniker de pointeur à droite d’un anti-moniker produit un composite générique plutôt que de composer à rien, comme ce serait le cas si l’ordre de composition était inversé.
Moniker de classe	Suit le contrat et se comporte comme un moniker d’élément en ce qu’il peut retourner E_INVALIDARG et MK_E_NEEDGENERIC, etc.
Moniker de fichier	Si pmkRight est un anti-moniker, le moniker retourné est NULL. Si pmkRight est un composite dont le composant le plus à gauche est un anti-moniker, le moniker retourné est le composite avec l’anti-moniker le plus à gauche supprimé. Si pmkRight est un moniker de fichier, cette méthode réduit les deux monikers en un seul moniker de fichier, si possible. Si ce n’est pas possible (par exemple, si les deux monikers de fichier représentent des chemins absolus, comme dans d :\work et e :\reports), le moniker retourné est NULL et la valeur de retour est MK_E_SYNTAX. Si pmkRight n’est ni un anti-moniker ni un moniker de fichier, la méthode vérifie le paramètre fOnlyIfNotGeneric ; si elle a la valeur FALSE, la méthode combine les deux monikers dans un composite générique ; si elle a la valeur TRUE, la méthode définit *ppmkComposite sur NULL et retourne MK_E_NEEDGENERIC.
Moniker composite générique	Si fOnlyIfNotGeneric a la valeur TRUE, cette méthode définit *pmkComposite sur NULL et retourne MK_E_NEEDGENERIC ; sinon, la méthode retourne le résultat de la combinaison des deux monikers en appelant la fonction CreateGenericComposite .
Moniker d’élément	Si pmkRight est un anti-moniker, le moniker retourné est NULL. Si pmkRight est un composite dont le composant le plus à gauche est un anti-moniker, le moniker retourné est le composite après la suppression du moniker le plus à gauche. Si pmkRight n’est pas un anti-moniker, la méthode combine les deux monikers en un composite générique si fOnlyIfNotGeneric a la valeur FALSE ; si fOnlyIfNotGeneric a la valeur TRUE, la méthode retourne un moniker NULL et une valeur de retour de MK_E_NEEDGENERIC.
MONIKER OBJREF	Si pmkRight est un anti-moniker, le moniker retourné est NULL. Si pmkRight est un composite dont le composant le plus à gauche est un anti-moniker, le moniker retourné est le composite avec l’anti-moniker le plus à gauche supprimé. Si pmkRight n’est ni un anti-moniker ni un moniker composite dont le composant le plus à gauche est un anti-moniker, la méthode vérifie le paramètre fOnlyIfNotGeneric . Si elle a la valeur FALSE, la méthode combine les deux monikers dans un composite générique ; si elle a la valeur TRUE, la méthode définit *ppmkComposite sur NULL et retourne MK_E_NEEDGENERIC.
Moniker de pointeur	Si pmkRight est un anti-moniker, le moniker retourné est NULL. Si pmkRight est un composite dont le composant le plus à gauche est un anti-moniker, le moniker retourné est le composite après la suppression du moniker le plus à gauche. Si fOnlyIfNotGeneric a la valeur FALSE, le moniker retourné est un composite générique des deux monikers ; sinon, la méthode définit *ppmkComposite sur NULL et retourne MK_E_NEEDGENERIC.
Moniker d’URL	Les monikers d’URL prennent en charge la composition de deux URL : une URL de base composée avec une URL relative. Cette composition est effectuée en fonction de la RFC sur les URL relatives. Si fOnlyIfNotGeneric a la valeur TRUE, la méthode retourne MK_E_NEEDGENERIC. Sinon, cette méthode renvoie simplement CreateGenericComposite(this, pmkRight, ppmkComposite).

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	objidl.h

Voir aussi

CreateGenericComposite

IMoniker