IOleLink Interface

IID_IOleLink

{0000011D-0000-0000-C000-000000000046}

The IOleLink interface is the means by which a linked object provides its container with functions pertaining to linking. The most important of these functions is binding to the link source, that is, activating the connection to the document that stores the linked object's native data. IOleLink also defines functions for managing information about the linked object, such as the location of the link source and the cached presentation data for the linked object.

A container application can distinguish between embedded objects and linked objects by querying for IOleLink; only linked objects implement IOleLink.

You must use IOleLink if you are writing a container application that allows its documents to contain linked objects. You primarily call IOleLink methods in order to implement the Links dialog box. If you use the OleUIEditLinks function to display the Links dialog box, your calls to IOleLink methods take place in your implementation of the IOleUILinkContainer interface.

Some IOleLink methods don't have to be called directly. Instead, you call methods of IOleObject; the default linked object provides an implementation of IOleObject that often calls methods of IOleLink. For example, a container application typically activates a linked object by calling IOleObject::DoVerb, which in turn calls IOleLink::BindToSource.

Methods in VTable order

IUnknown Methods

Description

QueryInterface

Returns pointers to supported interfaces.

AddRef

Increments reference count.

Release

Decrements reference count.

IOleLink Methods

Description

SetUpdateOptions

Sets the update options.

GetUpdateOptions

Returns the update options.

SetSourceMoniker

Sets the moniker for the link source.

GetSourceMoniker

Returns the moniker for the link source.

SetSourceDisplayName

Sets the display name for the link source.

GetSourceDisplayName

Returns the display name for the link source.

BindToSource

Binds the moniker to the link source.

BindIfRunning

Binds the moniker if the source is running.

GetBoundSource

Returns a pointer to the link source if it's running.

UnbindSource

Break connection to the link source.

Update

Update the cached views of the link source.

SetUpdateOptions

FUNCTION IOleLink_SetUpdateOptions ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL dwUpdateOpt AS DWORD _

  ) AS LONG
 

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[3] USING IOleLink_SetUpdateOptions (pthis, dwUpdateOpt) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

GetUpdateOptions

FUNCTION IOleLink_GetUpdateOptions ( _

  BYVAL pthis AS DWORD PTR _

, BYREF pdwUpdateOpt AS DWORD _

  ) AS LONG
 

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[4] USING IOleLink_GetUpdateOptions (pthis, pdwUpdateOpt) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

SetSourceMoniker

FUNCTION IOleLink_SetSourceMoniker ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pmk AS DWORD _

, BYREF rclsid AS GUID _

  ) AS LONG
 

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[5] USING IOleLink_SetSourceMoniker (pthis, pmk, rclsid) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

GetSourceMoniker

FUNCTION IOleLink_GetSourceMoniker ( _

  BYVAL pthis AS DWORD PTR _

, BYREF ppmk AS DWORD _

  ) AS LONG
 

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[6] USING IOleLink_GetSourceMoniker (pthis, ppmk) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

SetSourceDisplayName

FUNCTION IOleLink_SetSourceDisplayName ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL strDisplayName AS STRING _

  ) AS LONG
 

  LOCAL HRESULT AS LONG

  strDisplayname = UCODE$(strDisplayName) & $NUL
  CALL DWORD @@pthis[7] USING IOleLink_SetSourceDisplayName (pthis, strDisplayName) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

GetSourceDisplayName

FUNCTION Proto_IOleLink_GetSourceDisplayName ( _

  BYVAL pthis AS DWORD PTR _

, BYREF ppszDisplayName AS DWORD _

  ) AS LONG
 

FUNCTION IOleLink_GetSourceDisplayName ( _

  BYVAL pthis AS DWORD PTR _

, BYREF strDisplayName AS STRING _

  ) AS LONG
 

  LOCAL HRESULT AS LONG

  LOCAL bstrlen AS LONG

  LOCAL ppszDisplayName AS DWORD
  CALL DWORD @@pthis[8] USING Proto_IOleLink_GetSourceDisplayName (pthis, ppszDisplayName) TO HRESULT
  IF ISTRUE ppszDisplayName THEN
     bstrlen = lstrlenW(BYVAL ppszDisplayName )
     IF ISTRUE bstrlen THEN
        strDisplayName = PEEK$(ppszDisplayName , bstrlen * 2)
        strDisplayName = ACODE$(strDisplayName)
     END IF
     CoTaskMemFree ppszDisplayName
  END IF
  FUNCTION = HRESULT

END FUNCTION

BindToSource

FUNCTION IOleLink_BindToSource ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL bindflags AS DWORD _

, BYVAL pbc AS DWORD _

  ) AS LONG
 

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[9] USING IOleLink_BindToSource (pthis, bindflags, pbc) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

BindIfRunning

FUNCTION IOleLink_BindIfRunning ( _

  BYVAL pthis AS DWORD PTR _

  ) AS LONG
 

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[10] USING IOleLink_BindIfRunning (pthis) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

GetBoundSource

FUNCTION IOleLink_GetBoundSource ( _

  BYVAL pthis AS DWORD PTR _

, BYREF ppunk AS DWORD _

  ) AS LONG
 

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[11] USING IOleLink_GetBoundSource (pthis, ppunk) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

UnbindSource

FUNCTION IOleLink_UnbindSource ( _

  BYVAL pthis AS DWORD PTR _

  ) AS LONG
 

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[12] USING IOleLink_UnbindSource (pthis) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

Update

FUNCTION IOleLink_Update ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pbc AS DWORD _

  ) AS LONG
 

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[13] USING IOleLink_Update (pthis, pbc) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION