IOleLink::BindToSource

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This method activates the connection to the link source by binding the moniker stored within the linked object.

Syntax

HRESULT BindToSource(
  DWORD bindflags, 
  IBindCtx* pbc 
);

Parameters

• bindflags
  [in] Value that 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.

• pbc
  [in] 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

The following table shows the return values for this method.

Remarks

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.

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

Notes to Callers

Typically, your container application does not need to call the IOleLink::BindToSource method directly. When it is necessary to activate the connection to the link source, your container typically calls the IOleObject::DoVerb, IOleObject::Update, or IOleLink::Update method.

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.

When 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 a 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.

Requirements

See Also

Reference

OleRun
IBindCtx
IDataObject::DAdvise
IOleLink::Update
IOleLink::UnbindSource
IOleObject::Advise
IOleObject::DoVerb
OLELINKBIND