IMoniker

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

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
Windows Embedded CE	Windows CE 2.0 and later
Windows Mobile	Windows Mobile Version 5.0 and later

See Also

Reference

CreateAntiMoniker
CreateFileMoniker
CreateGenericComposite
CreateItemMoniker