Share via

IOleLink::SetSourceDisplayName

  • Article

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

HRESULT SetSourceDisplayName(
  LPCOLESTR pszStatusText
);

Parameters

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

Return Values

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 you use the OleUIEditLinks function to display the Links dialog box, you must implement the IOleUILinkContainer interface. The dialog box calls your implementations of the IOleUILinkContainer::SetLinkSource and IOleUILinkContainer::CancelLink methods. Your implementation of these methods can call 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

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

See Also

MkParseDisplayName | IOleLink::BindToSource | IOleLink::SetSourceMoniker

Last updated on Wednesday, April 13, 2005

© 2005 Microsoft Corporation. All rights reserved.