IOleLink::BindToSource method (oleidl.h)

Article
10/13/2021

Activates the connection to the link source by binding the moniker stored within the linked object.

Syntax

HRESULT BindToSource(
  [in] DWORD    bindflags,
  [in] IBindCtx *pbc
);

Parameters

[in] bindflags

Specifies how to proceed if the link source has a different CLSID from the last time it was bound. If this parameter is zero and the CLSIDs are different, the method fails and returns OLE_E_CLASSDIFF. If the OLELINKBIND_EVENIFCLASSDIFF value from the OLELINKBIND enumeration is specified and the CLSIDs are different, the method binds successfully and updates the CLSID stored in the linked object.

[in] pbc

A pointer to the IBindCtx interface on the bind context to be used in this binding operation. This parameter can be NULL. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the binding implementation should retrieve information about its environment. For more information, see IBindCtx.

Return value

This method returns S_OK on success. Other possible return values include the following.

Return code	Description
OLE_E_CLASSDIFF	The link source was not bound because its CLSID has changed. This error is returned only if the OLELINKBIND_EVENIFCLASSDIFF flag is not specified in the bindflags parameter.
MK_E_NOOBJECT	The link source could not be found or (if the link source's moniker is a composite) some intermediate object identified in the composite could not be found.
E_UNSPEC	The link's moniker is NULL.

Binding the moniker might require calling the CreateBindCtx function; therefore, this method may return errors generated by CreateBindCtx.

Remarks

Notes to Callers

Typically, your container application does not need to call the IOleLink::BindToSource method directly. When it's necessary to activate the connection to the link source, your container typically calls IOleObject::DoVerb, IOleObject::Update, or IOleLink::Update. The linked object's implementation of these methods calls IOleLink::BindToSource. Your container can also call the OleRun function, which calls IOleLink::BindToSource when called on a linked object.

In each of the examples listed previously, in which IOleLink::BindToSource is called indirectly, the bindflags parameter is set to zero. Consequently, these calls can fail with the OLE_E_CLASSDIFF error if the class of the link source is different from what it was the last time the linked object was bound. This could happen, for example, if the original link source was an embedded Lotus spreadsheet that an end user had subsequently converted (using the Change Type dialog box) to an Excel spreadsheet.

If you want your container to bind even though the link source now has a different CLSID, you can call IOleLink::BindToSource directly and specify OLELINKBIND_EVENIFCLASSDIFF for the bindflags parameter. This call binds to the link source and updates the link object's CLSID. Alternatively, your container can delete the existing link and use the OleCreateLink function to create a new linked object.

Notes to Implementers

The linked object caches the interface pointer to the link source acquired during binding.

The linked object's IOleLink::BindToSource implementation first tries to bind using a moniker consisting of the compound document's moniker composed with the link source's relative moniker. If successful, it updates the link's absolute moniker. Otherwise, it tries to bind using the absolute moniker, updating the relative moniker if successful.

If IOleLink::BindToSource binds to the link source, it calls the compound document's IOleContainer::LockContainer implementation to keep the containing compound document alive while the link source is running. IOleLink::BindToSource also calls the IOleObject::Advise and IDataObject::DAdvise implementations of the link source to set up advisory connections. The IOleLink::UnbindSource implementation unlocks the container and deletes the advisory connections.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	oleidl.h