IOleLink::SetSourceDisplayName

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

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

Syntax

HRESULT SetSourceDisplayName(
  LPCOLESTR pszStatusText
);

Parameters

• pszStatusText
  [in] Pointer to the display name of the new link source. It may can be NULL.

Return Value

If the method succeeds, the return value is S_OK.

Setting the display name requires calling MkParseDisplayName; therefore, this method can return errors generated by this function.

Remarks

The contract for IOleLink::SetSourceDisplayName does not specify when the linked object will parse the display name into a moniker. The parsing can occur before IOleLink::SetSourceDisplayName returns or the linked object can store the display name and parse it only when it needs to bind to the link source.

Note that parsing the display name is potentially an expensive operation because it might require binding to the link source.

The provided implementation of IOleLink::SetSourceDisplayName parses the display name and then releases the bind context used in the parse operation. This can result in running and then stopping the link source server.

If the linked object is bound to the current link source, the implementation of IOleLink::SetSourceDisplayName breaks the connection.

For more information about how the linked object stores and uses the moniker to the link source, see IOleLink::SetSourceMoniker.

Notes to Callers

Your container application can call IOleLink::SetSourceDisplayName when the user changes the source of a link or breaks a link.

Note that this requires the linked object to create a moniker out of the display name.

If you would rather parse the display name into a moniker yourself, your container can call IOleLink::SetSourceMoniker instead of IOleLink::SetSourceDisplayName.

If your container application is immediately going to bind to a newly specified link source, you should call the MkParseDisplayName function and IOleLink::SetSourceMoniker instead, and then call the IOleLink::BindToSource method using the bind context from the parsing operation.

By reusing the bind context, you can avoid the redundant loading of objects that might otherwise occur.

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

Requirements

See Also

Reference

MkParseDisplayName
IOleLink::BindToSource
IOleLink::SetSourceMoniker