Interface IMoniker (objidl.h)

Article
08/25/2023

Vous permet d’utiliser un objet moniker, qui contient des informations qui identifient un objet COM de manière unique. Un objet qui a un pointeur vers l’interface IMoniker de l’objet moniker peut localiser, activer et accéder à l’objet identifié sans avoir d’autres informations spécifiques sur l’emplacement réel de l’objet dans un système distribué.

Les monikers sont utilisés comme base pour la liaison dans COM. Un objet lié contient un moniker qui identifie sa source. Lorsque l’utilisateur active l’objet lié pour le modifier, le moniker est lié ; cela charge la source de lien en mémoire.

Héritage

L’interface IMoniker hérite d’IPersistStream. IMoniker a également ces types de membres :

Méthodes

L’interface IMoniker a ces méthodes.


IMoniker ::BindToObject Lie à l’objet spécifié. Le processus de liaison implique de rechercher l’objet, de le mettre à l’état d’exécution si nécessaire et de fournir à l’appelant un pointeur vers une interface spécifiée sur l’objet identifié.
IMoniker ::BindToStorage Lie au stockage de l’objet spécifié. Contrairement à la méthode IMoniker ::BindToObject, cette méthode n’active pas l’objet identifié par le moniker.
IMoniker ::CommonPrefixWith Crée un nouveau moniker basé sur le préfixe que ce moniker a en commun avec le moniker spécifié.
IMoniker ::ComposeWith Crée un moniker composite en combinant le moniker actuel avec le moniker spécifié.
IMoniker ::Enum Récupère un pointeur vers un énumérateur pour les composants d’un moniker composite.
IMoniker ::GetDisplayName Récupère le nom complet du moniker.
IMoniker ::GetTimeOfLastChange Récupère l’heure à laquelle l’objet identifié par ce moniker a été modifié pour la dernière fois.
IMoniker ::Hash Crée une valeur de hachage à l’aide de l’état interne du moniker.
IMoniker ::Inverse Crée un moniker qui est l’inverse de ce moniker. Lorsqu’il est composé à droite de ce moniker ou d’une structure similaire, le moniker ne compose à rien.
IMoniker ::IsEqual Détermine si ce moniker est identique au moniker spécifié.
IMoniker ::IsRunning Détermine si l’objet identifié par ce moniker est actuellement chargé et en cours d’exécution.
IMoniker ::IsSystemMoniker Détermine si ce moniker est l’une des classes moniker fournies par le système.
IMoniker ::P arseDisplayName Convertit un nom d’affichage en moniker.
IMoniker ::Reduce Réduit un moniker à sa forme la plus simple.
IMoniker ::RelativePathTo Crée un moniker relatif entre ce moniker et le moniker spécifié.

Remarques

Comme un chemin d’accès à un fichier dans un système de fichiers, un moniker contient des informations qui permettent à un objet COM d’être localisé et activé. Les monikers peuvent identifier n’importe quel type d’objet COM, d’un objet document stocké dans un fichier à une sélection dans un objet incorporé. COM fournit un ensemble de classes moniker qui vous permettent de créer des objets moniker identifiant les objets les plus couramment trouvés dans le système. Par exemple, il peut y avoir un objet représentant une plage de cellules dans une feuille de calcul qui est elle-même incorporée dans un document texte stocké dans un fichier. Dans un système distribué, le moniker de cet objet identifie l’emplacement du système de l’objet, l’emplacement physique du fichier sur ce système, le stockage de l’objet incorporé dans ce fichier et, enfin, l’emplacement de la plage de cellules dans l’objet incorporé.

Un objet moniker prend en charge l’interface IMoniker , qui est dérivée de l’interface IPersistStream et identifie de manière unique un seul objet dans le système. Une fois qu’un objet fournissant un moniker a créé l’objet moniker, ces informations ne peuvent pas être modifiées dans cet objet. Si le fournisseur de moniker modifie les informations, il ne peut le faire qu’en créant un nouvel objet moniker, qui identifierait ensuite de manière unique l’objet en question.

Les monikers ont les deux fonctionnalités importantes suivantes :

Les monikers peuvent être enregistrés dans un stockage persistant. Lorsqu’un moniker est de nouveau chargé en mémoire, il identifie toujours le même objet.
Les monikers prennent en charge une opération appelée liaison, qui consiste à localiser l’objet nommé par le moniker, à l’activer (le charger en mémoire) s’il n’est pas déjà actif et à retourner un pointeur vers une interface demandée sur cet objet.

Implémentation anti-moniker

Les anti-monikers sont l’inverse des implémentations COM des monikers de fichier, d’élément et de pointeur. Autrement dit, un anti-moniker composé à droite d’un moniker de fichier, d’un moniker d’élément ou d’un moniker pointeur compose à rien.

Si vous êtes un client moniker, vous n’avez généralement pas besoin d’utiliser des anti-monikers. Lorsque vous avez besoin de l’inverse d’un moniker, vous devez appeler IMoniker ::Inverse. Par exemple, si vous avez besoin d’un inverse pour supprimer la dernière partie d’un moniker composite, utilisez IMoniker ::Enum pour énumérer les éléments du moniker et appeler Inverse sur le morceau le plus à droite. Vous ne devez pas utiliser un anti-moniker à cet effet, car vous ne pouvez pas être sûr que la pièce la plus à droite d’un composite considère un anti-moniker comme son inverse.

La seule situation dans laquelle vous devez utiliser explicitement un anti-moniker est lorsque vous écrivez une nouvelle classe de moniker et que vous n’avez aucune exigence particulière pour construire des inverses à vos monikers. Dans ce cas, vous pouvez retourner des anti-monikers à partir de votre implémentation d’Inverse. Dans votre implémentation de IMoniker ::ComposeWith, vous devez ensuite anéantir l’un de vos monikers pour chaque anti-moniker que vous rencontrez.

Utilisez la fonction CreateAntiMoniker pour créer ces monikers.

Implémentation de Moniker de classe

Les monikers de classe sont des monikers qui représentent une classe d’objet. Les monikers de classe se lient à l’objet de classe de la classe pour laquelle ils sont créés.

Les monikers de classe sont plus utiles dans la composition avec d’autres types de monikers, tels que les monikers de fichier ou les monikers d’élément. Les monikers de classe peuvent également être composés à droite des monikers prenant en charge la liaison à l’interface IClassActivator . Cela permet à IClassActivator de fournir l’accès à l’objet de classe et aux instances de la classe.

Pour utiliser des monikers de classe, vous devez utiliser la fonction CreateClassMoniker pour créer ces monikers.

Implémentation de Moniker de fichier

Les monikers de fichiers sont des monikers qui représentent un chemin d’accès dans le système de fichiers ; un moniker de fichier peut identifier n’importe quel objet enregistré dans son propre fichier. Pour identifier les objets contenus dans un fichier, vous pouvez composer des monikers d’autres classes (par exemple, des monikers d’élément) à droite d’un moniker de fichier. Toutefois, le moniker à gauche d’un moniker de fichier dans un composite doit être un autre moniker de fichier, un anti-moniker ou un moniker de classe. Il est illégal, par exemple, qu’un moniker d’élément apparaisse à gauche d’un moniker de fichier dans un composite.

Notez qu’un anti-moniker est l’inverse d’un moniker de fichier entier, et non l’inverse d’un composant du chemin d’accès que le moniker représente ; autrement dit, lorsque vous composez un anti-moniker à droite d’un moniker de fichier, le moniker de fichier entier est supprimé. Si vous souhaitez supprimer uniquement le composant le plus à droite du chemin d’accès représenté par un moniker de fichier, vous devez créer un moniker de fichier distinct basé sur le chemin d’accès « .. », puis le composer jusqu’à la fin du moniker de fichier.

Un client moniker (à l’aide d’un moniker pour obtenir un pointeur d’interface vers un objet) n’a généralement pas besoin de connaître la classe du moniker ; il peut simplement appeler des méthodes à l’aide d’un pointeur d’interface IMoniker .

Un fournisseur de moniker (qui fournit des monikers qui identifient ses objets pour les rendre accessibles aux clients moniker) doit utiliser des monikers de fichier si les objets qu’ils identifient sont stockés dans des fichiers. Si chaque objet réside dans son propre fichier, les monikers de fichier sont le seul type nécessaire. Si les objets identifiés sont plus petits qu’un fichier, vous devez utiliser un autre type de moniker (par exemple, les monikers d’élément) en plus des monikers de fichier.

Pour utiliser des monikers de fichier, vous devez utiliser la fonction CreateFileMoniker pour créer les monikers. Pour permettre le chargement de vos objets lorsqu’un moniker de fichier est lié, vos objets doivent implémenter l’interface IPersistFile .

L’exemple le plus courant de fournisseurs moniker est celui des applications serveur COM qui prennent en charge la liaison. Si votre application serveur COM prend en charge la liaison uniquement à des documents basés sur des fichiers dans leur intégralité, les monikers de fichiers sont le seul type de moniker dont vous avez besoin. Si votre application serveur COM prend en charge la liaison à des objets plus petits qu’un document (tels que des sections d’un document ou des objets incorporés), vous devez utiliser des monikers d’élément ainsi que des monikers de fichier.

Implémentation du moniker composite générique

Un moniker composite générique est un moniker composite dont les composants n’ont aucune connaissance particulière les uns des autres.

La composition est le processus qui consiste à joindre deux monikers ensemble. Parfois, deux monikers de classes spécifiques peuvent être combinés d’une manière spéciale ; 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 seul moniker de fichier représentant le chemin d’accès complet. Il s’agit d’un exemple de composition non générique. La composition générique, en revanche, peut connecter n’importe quel monikers, quelle que soit leur classe. Étant donné qu’une composition non générique dépend de la classe des monikers impliqués, elle ne peut être effectuée que par l’implémentation d’une classe particulière de la méthode IMoniker ::ComposeWith . Vous pouvez définir de nouveaux types de compositions non génériques si vous écrivez une nouvelle classe moniker. En revanche, les compositions génériques sont effectuées par la fonction CreateGenericComposite .

Un client moniker (à l’aide d’un moniker pour obtenir un pointeur d’interface vers un objet) n’a généralement pas besoin de connaître la classe du moniker, ni de savoir s’il s’agit d’un composite générique ou d’un composite non générique ; il peut simplement appeler des méthodes à l’aide d’un pointeur d’interface IMoniker .

Un fournisseur de moniker (qui passe des monikers qui identifient ses objets pour les rendre accessibles aux clients moniker) peut avoir besoin de composer deux monikers ensemble. (Par exemple, si vous utilisez un moniker d’élément pour identifier un objet, vous devez le composer avec le moniker identifiant le conteneur de l’objet avant de le remettre.) Utilisez la méthode IMoniker ::ComposeWith pour ce faire, en appelant la méthode sur le premier moniker et en passant le deuxième moniker en tant que paramètre ; cette méthode peut produire un composite générique ou non générique.

La seule fois où vous devez créer explicitement un moniker composite générique est lorsque vous écrivez votre propre classe moniker. Dans votre implémentation de IMoniker ::ComposeWith, vous devez essayer d’effectuer une composition non générique chaque fois que possible ; si vous ne pouvez pas effectuer une composition non générique et que la composition générique est acceptable, vous pouvez appeler la fonction CreateGenericComposite pour créer un moniker composite générique.

Implémentation du moniker d’élément

Les monikers d’élément sont utilisés pour identifier des objets dans des conteneurs, tels qu’une partie d’un document, un objet incorporé dans un document composé ou une plage de cellules dans une feuille de calcul. Les monikers d’élément sont souvent utilisés en combinaison avec des monikers de fichier ; un moniker de fichier est utilisé pour identifier le conteneur tandis qu’un moniker d’élément est utilisé pour identifier l’élément dans le conteneur.

Un moniker d’élément contient une chaîne de texte ; cette chaîne est utilisée par l’objet conteneur pour distinguer l’élément contenu des autres. L’objet conteneur doit implémenter l’interface IOleItemContainer ; cette interface permet au code de moniker d’élément d’acquérir un pointeur vers un objet, en fonction uniquement de la chaîne qui identifie l’objet.

Un client moniker (à l’aide d’un moniker pour obtenir un pointeur d’interface vers un objet) n’a généralement pas besoin de connaître la classe du moniker ; il appelle simplement des méthodes à l’aide d’un pointeur d’interface IMoniker .

Un fournisseur de moniker (qui passe des monikers qui identifient ses objets pour les rendre accessibles aux clients moniker) doit utiliser des monikers d’éléments si les objets identifiés sont contenus dans un autre objet et peuvent être identifiés individuellement à l’aide d’une chaîne. Utilisez un autre type de moniker (par exemple, monikers de fichier) pour identifier l’objet conteneur.

Pour utiliser des monikers d’élément, vous devez utiliser la fonction CreateItemMoniker pour créer les monikers. Pour permettre le chargement de vos objets lorsqu’un moniker d’élément est lié, le conteneur de vos objets doit implémenter l’interface IOleItemContainer .

L’exemple le plus courant de fournisseurs de moniker est les applications COM qui prennent en charge la liaison. Si votre application COM prend en charge la liaison à des objets plus petits qu’un document basé sur un fichier, vous devez utiliser des monikers d’élément. Pour une application serveur qui permet de lier une sélection dans un document, vous utilisez les monikers d’élément pour identifier ces objets. Pour une application conteneur qui permet la liaison à des objets incorporés, vous utilisez les monikers d’élément pour identifier les objets incorporés.

Implémentation de moniker OBJREF

Les monikers OBJREF représentent une référence à un objet instance qui s’exécute sur un serveur hors processus, localement ou à distance. Le moniker identifie l’objet instance et l’ordinateur sur lequel l’objet s’exécute.

Un moniker OBJREF est similaire à bien des égards à un moniker de pointeur, sauf que l’objet en cours d’exécution est hors processus. Un client peut appeler IMoniker ::BindToObject sur un moniker OBJREF et utiliser le pointeur qu’il obtient pour accéder à l’objet en cours d’exécution, quel que soit son emplacement.

Une distinction importante par rapport à un moniker de pointeur est que le nom d’affichage d’un moniker OBJREF peut être incorporé dans une page HTML et que l’objet en cours d’exécution représenté par le moniker peut être lié par un script client, une applet ou un contrôle ActiveX.

L’utilisation principale d’un moniker OBJREF est d’obtenir l’accès à un objet en cours d’exécution instance via Internet. Une page de serveur actif ou un autre moyen de générer du contenu HTML dynamique place le nom d’affichage d’un moniker OBJREF dans un paramètre dans une applet ou un contrôle ActiveX. Le code de l’applet ou du contrôle appelle la fonction CreateObjrefMoniker pour créer un moniker OBJREF en fonction du nom d’affichage, puis appelle IMoniker ::BindToObject sur le moniker OBJREF résultant pour accéder à l’objet en cours d’exécution instance. La page du serveur actif marshale ensuite un pointeur vers l’objet en cours d’exécution vers le client de la page.

Implémentation du moniker du pointeur

Un moniker de pointeur encapsule essentiellement un pointeur d’interface afin qu’il ressemble à un moniker et puisse être passé aux interfaces qui nécessitent des monikers. La liaison d’un moniker de pointeur s’effectue en appelant la méthode QueryInterface du pointeur.

Les instances de monikers de pointeur refusent d’être sérialisées ; autrement dit, IPersistStream ::Save retourne une erreur. Ces monikers peuvent toutefois être marshalés vers un autre processus dans un appel RPC ; en interne, le système marshale et désactive le pointeur à l’aide du paradigme standard pour marshaler les pointeurs d’interface.

Les monikers de pointeur sont rarement nécessaires. Utilisez des monikers de pointeur uniquement si vous avez besoin de monikers pour identifier les objets qui n’ont aucune représentation persistante. Les monikers de pointeur permettent à ces objets de participer à une opération de liaison de moniker.

Implémentation du moniker d’URL

L’implémentation du moniker d’URL d’IMoniker se trouve sur un objet moniker d’URL, qui prend également en charge IUnknown et l’interface IAsyncMoniker . L’interface IMoniker hérite de sa définition d’IPersistStream ainsi que d’IUnknown, et IPersistStream hérite d’IPersist. Par conséquent, l’implémentation d’IMoniker inclut la prise en charge d’IPersistStream et D’IPersist.

L’interface IAsyncMoniker est simplement IUnknown. (Il n’existe aucune méthode supplémentaire.) Il permet aux clients de déterminer si un moniker prend en charge la liaison asynchrone.

Pour obtenir un pointeur vers l’interface IMoniker sur cet objet, appelez la fonction CreateURLMonikerEx .

Un client moniker (à l’aide d’un moniker pour obtenir un pointeur d’interface vers un objet) n’a généralement pas besoin de connaître la classe du moniker qu’il utilise ; il appelle simplement des méthodes à l’aide d’un pointeur d’interface IMoniker .

Un fournisseur de moniker (qui passe des monikers qui identifient ses objets pour les rendre accessibles aux clients moniker) doit utiliser des monikers d’éléments si les objets qu’il identifie sont contenus dans un autre objet et peuvent être identifiés individuellement à l’aide d’une chaîne. Il doit également utiliser un autre type de moniker (par exemple, monikers de fichier) pour identifier l’objet conteneur.

Configuration requise

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