Share via

IMoniker (Compact 2013)

  • Article

3/26/2014

This interface contains methods that allow you to use a moniker object, which contains information that uniquely identifies a Component Object Model (COM) object.

An object that has a pointer to the moniker object's IMoniker interface can locate, activate, and access the identified object without having any other specific information on where the object is actually located in a distributed system.

Like a path to a file in a file system, a moniker contains information that allows a COM object to be located and activated. Monikers can identify any type of COM object, from a document object stored in a file to a selection within an embedded object.

COM provides a set of moniker classes that allow you to create moniker objects identifying the objects most commonly found in the system. For example, there might be an object representing a range of cells in a spreadsheet that is itself embedded in a text document stored in a file.

In a distributed system, this object's moniker would identify the location of the object's system, the file's physical location on that system, the storage of the embedded object within that file, and, finally, the location of the range of cells within the embedded object.

A moniker object supports the IMoniker interface and uniquely identifies a single object in the system. Once an object providing a moniker has created the moniker object, this information cannot be changed within that object.

If the moniker provider changes the information, it can only do so by creating a new moniker object, which would then uniquely identify the object in question.

Monikers have two important capabilities:

  • Monikers can be saved to a persistent storage. When a moniker is loaded back into memory, it still identifies the same object.
  • Monikers support an operation called "binding," which is the process of locating the object named by the moniker, activating it (loading it into memory) if it is not already active, and returning a pointer to a requested interface on that object.

Monikers are used as the basis for linking in COM. A linked object contains a moniker that identifies its source. When the user activates the linked object to edit it, the moniker is bound; this loads the link source into memory.

When to Implement

Implement IMoniker only if you are writing a new moniker class. This is necessary only if you need to identify objects that cannot be identified using one of the COM-supplied moniker classes described below.

The COM-supplied moniker classes are sufficient for most situations. Before considering writing your own moniker class, you should make sure that your requirements cannot be satisfied by these classes.

When to Use

Two kinds of objects call the methods of IMoniker:

  • A component that contains one or more objects to be identified with a moniker and must provide the moniker to other objects
  • A client object that must bind to the object identified by the moniker

The component providing a moniker makes it accessible to other objects. It is important to understand the differences between the various system-supplied moniker classes to know which are appropriate for a given object. COM also provides functions for creating monikers using the COM-supplied moniker classes.

  • File monikers
    Based on a path in the file system. File monikers can be used to identify objects that are saved as files. The associated creation function is CreateFileMoniker.
  • Item monikers
    Based on a string that identifies an object in a container. Item monikers can be used to identify objects smaller than a file, such as embedded objects in a compound document and pseudo-objects (like a range of cells in a spreadsheet). The associated creation function is CreateItemMoniker.
  • Generic composite monikers
    Consists of two or more monikers of arbitrary type that have been composed together. Generic composite monikers allow monikers of different classes to be used in combination. The associated creation function is CreateGenericComposite.
  • Anti-monikers
    The inverse of file, item, or pointer monikers. Anti-monikers are used primarily for constructing relative monikers, which are analogous to relative path (such as "..\backup\report.old"), and which specify a location of an object relative to the location of another object). The associated creation function is CreateAntiMoniker.
  • Pointer monikers
    A non-persistent moniker that wraps an interface pointer to an object loaded in memory. Whereas most monikers identify objects that can be saved to persistent storage, pointer monikers identify objects that cannot. The associated creation function is CreatePointerMoniker.

A moniker provider must also implement other interfaces to allow the monikers it hands out to be bound. COM objects that commonly provide monikers are link sources. These include server applications that support linking and container applications that support linking to their embedded objects.

Binding to an object means that a client uses a moniker to locate the object, activate it when necessary, and get a pointer to one of the active object's interfaces. The client of the moniker does not need to be aware of the class of the moniker - it must just get a pointer to the correct moniker's IMoniker interface.

Monikers are used most often in this way by container applications that allow their documents to contain linked objects. However, link containers rarely call IMoniker methods directly. Instead, they generally manipulate linked objects through the default handler's implementation of the IOleLink interface, which calls the appropriate IMoniker methods as needed.

  • Class monikers
    These represent an object class. Class monikers bind to the class object of the class for which they are created.

Methods

The following table shows the methods for this interface in alphabetical order. Like all COM interfaces, this interface inherits the methods for the IUnknown interface.

Method

Description

IMoniker::BindToObject

Binds to the object named by the moniker.

IMoniker::BindToStorage

Binds to the object's storage.

IMoniker::CommonPrefixWith

Finds the prefix that the moniker has in common with another moniker.

IMoniker::ComposeWith

Composes with another moniker.

IMoniker::Enum

Enumerates component monikers.

IMoniker::GetDisplayName

Returns the display name.

IMoniker::GetTimeOfLastChange

Returns the time the object was last changed.

IMoniker::Hash

Returns a hash value.

IMoniker::Inverse

Returns the inverse of the moniker.

IMoniker::IsEqual

Compares one moniker with another moniker.

IMoniker::IsRunning

Checks whether object is running.

IMoniker::IsSystemMoniker

Checks whether moniker is one of the system-supplied types.

IMoniker::ParseDisplayName

Converts a display name into a moniker.

IMoniker::Reduce

Reduces the moniker to the simplest form.

IMoniker::RelativePathTo

Constructs a relative moniker between the specified moniker and another.

Remarks

To determine whether the platform supports this interface, see Determining Supported COM APIs.

Requirements

Header

objidl.h,
objidl.idl

Library

ole32.lib,
uuid.lib

See Also

Reference

COM Interfaces
CreateAntiMoniker
CreateFileMoniker
CreateGenericComposite
CreateItemMoniker