IMoniker—OBJREF Moniker Implementation

OBJREF monikers represent a reference to an object instance that is running on an out-of-process server, either locally or remotely. The moniker identifies the object instance and the computer the object is running on.

An OBJREF moniker is similar in many ways to a pointer moniker, except that the running object is out-of-process. A client can call IMoniker::BindToObject on an OBJREF moniker and use the pointer it obtains to access the running object, regardless of its location.

An important distinction from a pointer moniker is that the display name of an OBJREF moniker can be embedded in an HTML page, and the running object represented by the moniker can be bound by a client script, applet, or ActiveX control.

The primary use for an OBJREF moniker is to obtain access to a running object instance over the Internet. An active server page or some other means of generating dynamic HTML content places the display name of an OBJREF moniker in a parameter to an applet or an ActiveX control. The code of the applet or control calls CreateObjrefMoniker to create an OBJREF moniker based on the display name, and it then calls IMoniker::BindToObject on the resulting OBJREF moniker to get access to the running object instance. The active server page then marshals a pointer to the running object back to the page's client.

IMoniker::BindToObject
For OBJREF monikers, the pmkToLeft parameter must be NULL. Because the OBJREF moniker represents a running object, no activation takes place. If the represented object is no longer running, BindToObject fails with E_UNEXPECTED.

IMoniker::BindToStorage
This method obtains a marshaled pointer to the requested interface on the storage that contains the running object. Because the OBJREF moniker represents a running object, no activation takes place. If the represented object is no longer running, BindToStorage fails with E_UNEXPECTED.

IMoniker::Reduce
This method returns MK_S_REDUCED_TO_SELF and passes back the same moniker.

IMoniker::ComposeWith
If pmkRight is an anti-moniker, the returned moniker is NULL. If pmkRight is a composite whose leftmost component is an anti-moniker, the returned moniker is the composite with the leftmost anti-moniker removed. If pmkRight is neither an anti-moniker nor a composite moniker whose leftmost component is an anti-moniker, the method checks the fOnlyIfNotGeneric parameter. If it is FALSE, the method combines the two monikers into a generic composite; if it is TRUE, the method sets *ppmkComposite to NULL and returns MK_E_NEEDGENERIC.

IMoniker::Enum
This method returns S_OK and sets ppenumMoniker to NULL.

IMoniker::IsEqual
This method returns S_OK if *pmkOther is an OBJREF moniker and the paths for both monikers are identical (using a case-insensitive comparison). Otherwise, the method returns S_FALSE.

IMoniker::Hash
This method calculates a hash value for the moniker.

IMoniker::IsRunning
Because OBJREF monikers represent a running object instance, this method returns TRUE unless the object is known to be no longer running because a recent call failed. The method ignores pmkToLeft.

IMoniker::GetTimeOfLastChange
This method returns E_NOTIMPL.

IMoniker::Inverse
This method returns an anti-moniker (that is, the results of calling CreateAntiMoniker).

IMoniker::CommonPrefixWith
If the two monikers are equal, this method returns MK_S_US and sets *ppmkPrefix to NULL. If the other moniker is not an OBJREF moniker, this method passes both monikers to the MonikerCommonPrefixWith function. This function correctly handles the case where the other moniker is a generic composite.

If there is no common prefix, this method returns MK_E_.

IMoniker::RelativePathTo
This method returns E_NOTIMPL.

IMoniker::GetDisplayName
This method obtains the display name for the OBJREF moniker. The display name is a 64-bit encoding that encapsulates the machine location, process endpoint, and interface pointer ID (IPID) of the running object. For future compatibility, the display name is restricted to characters that can be specified as part of a URL.

IMoniker::ParseDisplayName
If pmkToLeft is not NULL, this method returns MK_E_SYNTAX.

IMoniker::IsSystemMoniker
This method returns S_OK and passes back MKSYS_OBJREFMONIKER.

Send comments about this topic to Microsoft.
Show: