IMoniker

The IMoniker interface is used for naming COM objects. An object that implements IMoniker is called a "moniker," which is a name that uniquely identifies a COM object.

You can think of a moniker as a generalization of a pathname; in the same way that a pathname identifies a file in the file system, a moniker identifies a COM object. For example, suppose you have an object representing a range of cells in a spreadsheet which is itself embedded in a text document. The moniker for this object would contain information like "c:\work\report.doc\embedobj1\A1:E7." Monikers are more widely applicable than pathnames; whereas pathnames can only identify files, monikers can identify any kind of object, whether it's a file, an embedding, a selection within a document, or something else.

Monikers have a number of useful properties:

• Monikers can be saved to a persistent storage. When a moniker is loaded back into memory, it still identifies the same object it did before.

• Monikers support an operation called "binding," which is the process of locating the object named by the moniker, activating it (loading it in memory) if it isn't already, and returning an interface pointer to it.

As a result of these characteristics, you can treat monikers as a persistent version of a pointer to an object. Suppose your object holds an ICellRange pointer to the cell-range object mentioned in the paragraph above. You'd like to save your object and the cell-range object to disk, reload them later, and still have your object hold a pointer to the cell-range object. It's no use saving the ICellRange pointer to a disk file, because you can't guarantee that the cell-range object will reside at the same address in memory the next time it's loaded. However, you can save a moniker in a file. Then you can re-read the moniker into memory and bind the moniker, which reloads the cell-range object into memory and returns an ICellRange pointer to it. You've thus reestablished a connection between two objects after writing them to persistent storage.

Monikers also form 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

You implement IMoniker only if you are writing your own moniker class; this is necessary only if you need to identify objects that cannot be identified using the system-supplied moniker classes.

The system supplies the following moniker classes:

• File monikers based on a path in the file system. File monikers can be used to identify objects that are saved in their own files.

• 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, including embedded objects in a compound document, or a pseudo-object (like a range of cells in a spreadsheet).

• 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.

• Anti-monikers the inverse of file, item, or pointer monikers. Anti-monikers are used primarily for constructing relative monikers, which are analogous to relative pathnames (such as "..\backup\report.old"), and which specifies a location of an object relative to the location of another object).

• 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; they allow such objects to participate in a moniker binding operation.

These system-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 system-supplied moniker classes. See the description for each moniker class for information on how each one implements the IMoniker interface.

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

You can use monikers whenever you need to create persistent connections between objects. You can also use monikers if you need a naming mechanism more general than pathnames; for example, if you need to designate embedded objects as well as files.

You can use monikers in two ways:

• As a moniker provider; that is, handing out monikers that identify your objects to make them accessible to other parties. When acting as a moniker provider, you need to understand the differences between the various system-supplied moniker classes in order to know which one(s) are appropriate for identifying your objects. You use certain API functions to create monikers, and you must implement other interfaces to allow the monikers you hand out to be bound.

• As a moniker client; that is, using monikers to get interface pointers to objects managed by a moniker provider. When acting as a moniker client, you typically don't need to know the class of the moniker you're using; you simply call methods using an IMoniker interface pointer.

The most common example of moniker providers are applications that act as link sources; that is, server applications that support linking and container applications that support linking to the embedded objects in their documents. See the descriptions for the moniker classes and for the moniker creation API functions for information on when to use each class.

The most common example of moniker clients are applications that act as link containers; that is, container applications that allow their documents to contain linked objects. However, link containers are a special case in that they make only infrequent calls to IMoniker methods. Generally, they manipulate linked objects through the IOleLink interface; the default handler implements this interface and calls the appropriate IMoniker methods as needed.

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

Software for developers

Delphi Components
.Net Components
Software for Android Developers

More information resources

MegaDetailed.Net
Unix Manual Pages
Delphi Examples

Databases for Amazon shops developers

Amazon Categories Database
Browse Nodes Database