IOleLink::SetSourceMoniker (Windows CE 5.0)

Send Feedback

This method specifies the new link source of a linked object using a moniker.

HRESULT SetSourceMoniker(IMoniker* pmk,REFCLSIDrclsid);

Parameters

  • pmk
    [in] Pointer to the IMoniker interface on a moniker that identifies the new link source of the linked object. A value of NULL breaks the link.
  • rclsid
    [in] CLSID of the link source that the linked object should use to access information about the linked object when it is not bound.

Return Values

If the moniker was set successfully, the method returns S_OK.

Remarks

The IOleLink contract does not specify how the linked object stores or uses the link source moniker.

The provided implementation stores the absolute moniker specified when the link is created or when the moniker is changed; it then computes and stores a relative moniker.

Future implementations might manage monikers differently to provide better moniker tracking.

The absolute moniker provides the complete path to the link source. The linked object uses this absolute moniker and the moniker of the compound document to compute a relative moniker that identifies the link source relative to the compound document that contains the link.

pmkCompoundDoc->RelativePathTo(pmkAbsolute, ppmkRelative) 

When binding to the link source, the linked object first tries to bind using the relative moniker. If that fails, it tries to bind the absolute moniker.

When the linked object successfully binds using either the relative or absolute moniker, it automatically updates the other moniker.

The linked object also updates both monikers when it is bound to the link source and it receives a rename notification through the IAdviseSink::OnRename method.

A container application can also use the IOleLink::SetSourceDisplayName method to change a link's moniker.

The linked object's implementation of the IPersistStorage::Save method saves both the relative and absolute moniker.

Notes to Callers

Your container application can call IOleLink::SetSourceMoniker when the user changes the source of a link or breaks a link. Note that this requires your container to use the MkParseDisplayName function to create a moniker out of the display name that the user enters.

If you would rather have the linked object perform the parsing, your container can call IOleLink::SetSourceDisplayName instead of IOleLink::SetSourceMoniker.

The user changes the source of a link or breaks a link using the Links dialog box.

If you use the OleUIEditLinks function to display the Links dialog box, you must implement the IOleUILinkContainer interface.

The dialog box calls your implementations of IOleUILinkContainer::SetLinkSource and IOleUILinkContainer::CancelLink; your implementation of these methods can call IOleLink::SetSourceMoniker.

If the linked object is currently bound to its link source, the linked object's implementation of IOleLink::SetSourceMoniker closes the link before changing the moniker.

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

Requirements

OS Versions: Windows CE 3.0 and later.
Header: Oleidl.h, Oleidl.idl.
Link Library: Ole32.lib, Uuid.lib.

See Also

MkParseDisplayName | IMoniker | IOleLink | IAdviseSink::OnRename | IOleLink::SetSourceDisplayName | IPersistStorage::Save

Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.