Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
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 OLELINKBINDenumeration 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 IBindCtxinterface 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.

Value Description

S_OK

The link source is bound.

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

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.

CreateBindCtxerrors

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

Remarks

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

The linked object's IOleLink::BindToSourceimplementation 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::BindToSourcebinds to the link source, it calls the compound document's IOleContainer::LockContainerimplementation to keep the containing compound document alive while the link source is running.

IOleLink::BindToSourcealso calls the IOleObject::Adviseand IDataObject::DAdviseimplementations of the link source to set up advisory connections. The IOleLink::UnbindSourceimplementation 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::BindToSourcemethod directly. When it is necessary to activate the connection to the link source, your container typically calls the IOleObject::DoVerb, IOleObject::Update, or IOleLink::Updatemethod.

The linked object's implementation of these methods calls IOleLink::BindToSource. Your container can also call the OleRunfunction, which calls IOleLink::BindToSourcewhen called on a linked object.

When IOleLink::BindToSourceis called indirectly, the bindflagsparameter 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 Typedialog 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::BindToSourcedirectly and specify OLELINKBIND_EVENIFCLASSDIFF for the bindflagsparameter.

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 OleCreateLinkfunction to create a new linked object.

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

See Also