IMoniker

The IMoniker interface contains methods that allow you to use a moniker object, which contains information that uniquely identifies a COM object. An object that has a pointer to the moniker object’s IMoniker interface can locate, activate, and get access to 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. OLE 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 which 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, which is derived from the IPersistStream 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 capabilites:

• 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 OLE. 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 OLE-supplied moniker classes described below.

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

If you decide you need to write your own implementation of IMoniker, you must also implement the IROTData interface on your moniker class. This interface allows your monikers to be registered with the Running Object Table (ROT).

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. OLE also provides functions for creating monikers using the OLE-supplied moniker classes.

• File monikers &emdash; 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 &emdash; 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 &emdash; 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&emdash; 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 &emdash; 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. OLE 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 &emdash; 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 &emdash; these represent an object class. Class monikers bind to the class object of the class for which they are created. The associated creation function is CreateClassComposite.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.

IPersist Methods	Description
GetClassID	Returns the object’s CLSID.

IPersistStream Methods	Description
IsDirty	Checks whether object has been modified.
Load	Loads the object from a stream.
Save	Saves the object to a stream.
GetSizeMax	Returns the buffer size needed to save the object.

IMoniker Methods	Description
BindToObject	Binds to the object named by the moniker.
BindToStorage	Binds to the object’s storage.
Reduce	Reduces the moniker to simplest form.
ComposeWith	Composes with another moniker.
Enum	Enumerates component monikers.
IsEqual	Compares with another moniker.
Hash	Returns a hash value.
IsRunning	Checks whether object is running.
GetTimeOfLastChange	Returns time the object was last changed.
Inverse	Returns the inverse of the moniker.
CommonPrefixWith	Finds the prefix that the moniker has in common with another moniker.
RelativePathTo	Constructs a relative moniker between the moniker and another.
GetDisplayName	Returns the display name.
ParseDisplayName	Converts a display name into a moniker.
IsSystemMoniker	Checks whether moniker is one of the system-supplied types.

See Also

BindMoniker, CreateBindCtx, CreateGenericComposite, CreateFileMoniker, CreateItemMoniker, CreateAntiMoniker, CreatePointerMoniker, IOleLink, IPersistStream, IROTData, IMoniker&emdash;AntiMoniker Implementation, IMoniker&emdash;File Moniker Implementation, IMoniker&emdash;Item Moniker Implementation, IMoniker&emdash;Generic Composite Moniker Implementation, IMoniker&emdash;Pointer Moniker Implementation