IOleLink::SetSourceMoniker

Article
11/18/2015

A version of this page is also available for

4/8/2010

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

Syntax

HRESULT SetSourceMoniker(
  IMoniker* pmk,
  REFCLSID rclsid 
);

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 Value

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

Header	Oleidl.h, oleidl.idl
Library	ole32.lib, uuid.lib
Windows Embedded CE	Windows CE 3.0 and later
Windows Mobile	Windows Mobile Version 5.0 and later

Partager via