Programming Reference: ODLinkSource

# Programming Reference

## ODLinkSource

Class definition file | LinkSrc.idl
Class C++ Binding | LinkSrc.xh

Class hierarchy

    SOMObject
       ODObject
          ODRefCntObject
             ODPersistentObject
                ODBaseLinkSource
                   ODLinkSource

Description

An object of the ODLinkSource class represents the source of an OpenDoc link. Link-source objects are created and maintained by draft objects when the user creates a link between parts.

Linking is a mechanism for associating data in one part, the source, with data in another location, the destination. When the source data changes, the destination data can be updated manually or automatically. For example, linking allows the user to paste a spreadsheet graph to a financial report so subsequent changes to the spreadsheet are reflected in the report.

Links are created during paste or drop operations. The source and destination can be in the same part, in different parts of the same document, or in different documents. A link is a persistent, one-way conduit; updating occurs from the source to the destination only. Link sources are represented by ODLinkSource objects; link destinations are represented by ODLink objects. Source parts reference only link-source objects, and destination parts reference only link objects. These reference restrictions are important in ensuring the proper behavior when linked content is copied or moved.

When a source part that supports linking writes to the clipboard or drag-and-drop object, it uses a link specification to advertise its ability to create links. The source part creates a link specification (an object of class ODLinkSpec) by calling its draft's CreateLinkSpec method. In addition to writing the source content to the clipboard or drag-and-drop object, the source part writes link-specification data to the kODPropLinkSpec property.

When the user requests a link, the destination part asks for a link object by calling its draft's AcquireLink method. If the source part is in the same document, the draft calls the source part's CreateLink method. If the source part has not already created a link-source object for the source content described by the link specification, the source part call its draft's CreateLinkSource method to create a link-source object. The source part's draft is responsible for both the transitory and persistent storage of its link-source object. If the source part is in a different document, the link manager creates a cross-document link.

When a source part is recreated from stored data, its InitPartFromStorage method can call the draft object's AcquireLinkSource method to recreate the link-source object from storage.

If your part contains a link source, you are responsible for drawing an appropriate border around the linked content when requested to do so. If the user selects any content within the link, or checks the Shows Links setting of the Document Info dialog box, you must show the border of the link source when you draw. You can check whether to show links by calling the window's ShouldShowLinks method before drawing your part's content. If the user cuts content from your part that includes a link source, your part relinquishes ownership of the link-source object. If the user subsequently undoes the action, you must call the SetSourcePart method of the link-source objects to reclaim ownership.

Every link source has an associated update ID that uniquely identifies the current generation or version of its content. The source part sets the update ID for when ever it creates or updates the content of a link-source object. The destination part stores the ID that was current when it last updated its content from the link.

For further information on the implementation of OpenDoc links, see the class descriptions for ODLink and ODLinkSpec, and the chapter on data transfer in the OpenDoc Programming Guide.

Creating Multiple Destinations for a Link

If your part is the source part for a link, its CreateLink method may be called multiple times with the same link specification to create multiple destinations for the same link. If you write data to the content storage unit of the link-source object when you first create it, your CreateLink method can simply return the link-source object on subsequent calls; however, if you write promises, you need to ensure that all part kinds originally promised are present in the content storage unit. The initial destination caused your part to fulfill promises of the part kinds that it copied but might have left unfulfilled promises for other part kinds. If the draft was saved, those unfulfilled promises were removed. To add a new destination, you need to clear the content storage unit and rewrite promises for all part kinds. First, call the link-source object's GetUpdateID method to get its current update ID. Next, pass that ID as the parameter when you call the Clear method. Because the ID is not being changed, the link-source object keeps track of the nonpromise part kinds that were in the content storage unit when you cleared it. When you subsequently write promises for those part kinds, the link-source object automatically forces the source part to fulfill them. Thus, you can ensure that the content storage unit contains all the data needed by the initial destination part and promises for the other part kinds that might be needed by the new destination part.

Data Transfer from Source to Destination

The process of transferring content from a link source to a link destination requires three steps. First, the source part transfers content to the link-source object. Second, the link-source object transfers content to each of its associated link objects. Third, each destination part must read the content from its link object.

Update Mode

Every link-source object has an update mode that affects the first two steps of the transfer from source part to destination part. The source part should use the update mode to determine when to transfer content to the link-source object. The link-source object uses the update mode to determine when to send updated content to its associated link object in other documents. When the source part updates the link-source object, the link-source object immediately sends the updated content to its associated link objects in the same document.

- The automatic update mode indicates that the source part should update the link-source object if the source content has changed; the link-source object sends those updates to destinations in other documents when its draft is saved. This mode is the default.

- The manual update mode indicates that the source part should update the link-source object only when the user clicks the Update Now button in the Link Source Info dialog box; the link-source object immediately sends those updates to destinations in other documents.

Source Part to Link-Source Object

If your part is the source part of a link, you should use the update mode of the link-source object to determine when to transfer data. Several methods are required to effect the data transfer.

Because source and destination parts may attempt to access a link simultaneously, parts must acquire a lock before they transfer link data. You can lock the link-source object by calling its Lock method.

Once the link-source object is locked, you can obtain a reference to its content storage unit by calling the GetContentStorageUnit method. You must not cache that storage unit; you must call the GetContentStorageUnit method when you need to access the storage unit.

If you are updating the content, instead of writing the initial content, you should call the link-source object's Clear method before you write to the content storage unit.

You can call the appropriate methods of the content storage unit to write data to it. If you need to clone objects, call the cloning methods of your part's draft object. For more information, see the descriptions of the classes ODStorageUnit and ODDraft.

After writing initial content or updates to the link-source object's content storage unit, you must notify the link-source object that you have updated its content by calling its ContentUpdated method. Finally, you should unlock the link-source object by calling its Unlock method.

Link-Source Object to Link Object

The link-source object automatically transfers new content to its associated link objects. This step requires no action by the source part or the destination part. As mentioned previously, the time when this transfer occurs varies depending on the update mode of the link-source object and whether the link object is in the same document as the link-source object.

Link Object to Destination Part

Every destination part is responsible for updating its destination content from the link object. A destination part can register itself for automatic notification of updates by calling the RegisterDependent method of a link object. A registered destination part should update its content from the link content when it is notified of an update; an unregistered part should update its content when the user clicks the Update Now button in the Show Link Destination Info dialog box.

Methods

The methods defined by the ODLinkSource class include:

- Clear
- ContentUpdated
- GetChangeTime
- GetContentStorageUnit
- GetDescription (OS/2)
- GetUpdateID
- IsAutoUpdate
- Lock
- SetAutoUpdate
- SetDescription (OS/2)
- SetSourcePart
- ShowLinkSourceInfo
- Unlock

Overridden Methods | There are no methods overridden by the ODLinkSource class.

### Clear

This method clears the content of this link-source object.

Signature

    void Clear (ODUpdateID id,
                ODLinkKey key)

Parameters

id (ODUpdateID) - input

  The update ID associated with the new empty content.

key (ODLinkKey) - input

  A valid link key obtained by a prior call to the Lock method.

Returns

None.

Remarks

If your part is the source part for this link-source object, you call this method to remove the link-source object's previous content before updating the source data. This method removes all data in the content property (kODPropContents) from the link-source object's content storage unit.

The id parameter identifies the new version of this link-source object's content; its value depends on the circumstances in which this method is called:

- If your part originated the changes to its source content, the id parameter should be a new update ID that you obtained by calling the session object's UniqueUpdateID method.

- If the changes occurred because the source content of this link contains the destination content of another link that was updated, the id parameter should be the updated ID that your part received when it was notified to update the destination content within the source content for this link.

- If your part originally created this link-source object with promise data and its CreateLink method is being called again to create a new link destination, the id parameter should be the current update ID for this link-source object. Your can call the GetUpdateID method to get the current update ID.

  To add a new destination for this link-source object, you need to clear the content storage unit and rewrite promises for all part kinds. Because the ID is not being changed, the link-source object keeps track of the nonpromise part kinds that were in the content storage unit when you cleared it. When you subsequently rewrite promises for those part kinds, the link-source object automatically forces the source part to fulfill them; you should not call the link-source object's ContentUpdated method after rewriting those promises.

The key parameter ensures thread safety. Before calling this method, you must call this link-source object's Lock method to obtain this key.

Exception Handling

kODErrInvalidLinkKey | The key parameter is not a valid key for this link-source object.
kODErrInvalidPermissions | Draft permissions do not allow modifications.
kODErrUnknownUpdateID | The specified update ID is the reserved value kODUnknownUpdate.

Related Methods

- ODLinkSource::GetContentStorageUnit
- ODLinkSource::GetUpdateID
- ODLinkSource::Lock
- ODSession::UniqueUpdateID

### ContentUpdated

This method notifies this link-source object that its content has been updated.

Signature

    void ContentUpdated (ODUpdateID id,
                         ODLinkKey key)

Parameters

id (ODUpdateID) - input

  The update ID associated with the new content.

key (ODLinkKey) - input

  A valid link key obtained by a prior call to the Lock method.

Returns

None.

Remarks

If your part is the source part for this link-source object, you call this method after writing the initial content to the content storage unit of this link-source object and after making changes to the content of that storage unit.

The id parameter identifies the new version of the link source object's content; its value depends on the circumstances in which this method is called:

- If you called the Clear method before calling this method, the id parameter should be the same update ID that you passed to the Clear method.

- If your part originated the changes to its source content, the id parameter should be a new update ID that you can be obtained by calling the session object's UniqueUpdateID method.

- If the changes occurred because the source content of this link contains the destination content of another link that was updated, the id parameter should be the updated ID that your part received when it was notified to update the destination content within the source content for this link.

The key parameter ensures thread safety. Before calling this method, you must call the Lock method to obtain this key.

Exception Handling

kODErrInvalidLinkKey | The key parameter is not a valid key for this link-source object.
kODErrUnknownUpdateID | The specified update ID is the reserved value kODUnknownUpdate.

Related Methods

- ODFrame::ChangeLinkStatus
- ODFrame::ContentUpdated
- ODLinkSource::GetUpdateID
- ODLinkSource::Lock
- ODPart::EmbeddedFrameUpdated
- ODSession::UniqueUpdateID

### GetChangeTime

This method returns the time that this link-source object was last updated.

Signature

    ODTime GetChangeTime ()

Parameters

None.

Returns

rv (ODTime) - returns

  The time when this link source was last updated.

### GetContentStorageUnit

This method returns a reference to the content storage unit for this link-source object.

Signature

    ODStorageUnit *GetContentStorageUnit (ODLinkKey key)

Parameters

key (ODLinkKey) - input

  A valid link key obtained by a prior call to the Lock method.

Returns

rv (ODStorageUnit *) - returns

  A reference to this link-source object's content storage unit.

Remarks

The key parameter ensures thread safety. Before calling this method, you must call the Lock method to obtain this key.

The returned storage unit remains valid until the key is relinquished by the Unlock method. The link-source object handles the creation and destruction of its content storage unit, so you cannot dispose of or release the returned storage unit.

You must not cache the returned storage unit; you must call this method when you need to access the content storage unit.

Exception Handling

kODErrInvalidLinkKey | The key parameter is not a valid key for this link-source object.

Related Methods

- ODLinkSource::Lock
- ODLinkSource::Unlock

### GetDescription (OS/2)

This method is called by the source part to get the link-source object's description.

Signature

    void GetDescription (ODLinkDescription *desc)

Parameters

desc (ODLinkDescription *) - output

  A string containing part-specific information.

Returns

None.

Remarks

The part description could include information such as the part kind, name, and type, and more specific information as to how the linked content is being used in the destination part.

### GetUpdateID

This method returns the update ID that uniquely identifies the current generation or version of this link-source object's content.

Signature

    ODUpdateID GetUpdateID ()

Parameters

None.

Returns

rv (ODUpdateID) - returns

  The update ID of this link-source object's content.

Remarks

If your part is the source part for this link-source object, you can call this method to determine the current version of this link-source object's content.

You can compare the returned update ID with a previously saved ID to establish whether the content needs to be updated. There is no implicit ordering of update ID values; they offer tests for equality only, with no indication of the time or nature of any link changes.

Related Methods

- ODLinkSource::GetChangeTime

### IsAutoUpdate

This method indicates whether the link-source object's update mode is automatic.

Signature

    ODBoolean IsAutoUpdate ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the update mode for this link-source object is automatic.

  kODTrue | Update mode is set to is automatic. This is the default setting.
  kODFalse | Update mode is set to manual.

Remarks

If your part is the source part of this link-source object, you can call this method to determine when your part should update the content of this link-source object.

If this method returns kODTrue, you should update this link-source object when the source content is changed. If it returns kODFalse, your part should update this link-source object when the user clicks the Update Now button in the Link Source Info dialog box. When your part updates this link-source object, it should call the ContentUpdated method.

The update mode can be changed by the SetAutoUpdate method.

Related Methods

- ODLinkSource::ContentUpdated
- ODLinkSource::SetAutoUpdate

### Lock

This method locks this link-source object, ensuring exclusive access to its content storage unit.

Signature

    ODBoolean Lock (ODULong wait,
                    ODLinkKey *key)

Parameters

wait (ODULong) - input

  The time interval to wait for access to be granted. A value of 0 means no wait and is the only value accepted.

key (ODLinkKey *) - output

  A valid link key. If access is denied, this parameter contains an undefined, invalid key.

Returns

rv (ODBoolean) - returns

  A flag indicating whether access is granted.

  kODTrue | Access is granted.
  kODFalse | Access is denied.

Remarks

To ensure thread-safe access, you must call this method to acquire a valid link key before you write the link data. This method grants exclusive access to this link-source object's content; nested calls to the Lock method deny access.

While your part has the link-source object locked, you must pass the key returned in the key output parameter to all methods that access or modify the link-source object, such as the Clear, ContentUpdated, and GetContentStorageUnit methods. When you are finished modifying the link-source object, you must pass this key to the Unlock method to unlock the link-source object.

Exception Handling

kODErrBrokenLink | Internal error; the link-source object disconnected from its destination.

Related Methods

- ODLinkSource::Clear
- ODLinkSource::ContentUpdated
- ODLinkSource::GetContentStorageUnit
- ODLinkSource::Unlock

### SetAutoUpdate

This method sets this link-source object's update mode to automatic or manual.

Signature

    void SetAutoUpdate (ODBoolean automatic)

Parameters

automatic (ODBoolean) - input

  A flag indicating whether the update mode for this link-source object is to be automatic.

  kODTrue | The update mode is to be automatic.
  kODFalse | The update mode is to be manual.

Returns

None.

Remarks

Your part should use the new update mode to determine when to update the content of this link-source object. If the automatic parameter is kODTrue, your part should update this link-source object when the source content is changed. If the parameter is kODFalse, your part should update this link-source object when the user clicks the Update Now button in the Link Source Info dialog box. When your part updates this link-source object, it should call the ContentUpdated method.

Related Methods

- ODLinkSource::ContentUpdated
- ODLinkSource::IsAutoUpdate

### SetDescription (OS/2)

This method is called by the source part to set the link source's description.

Signature

    void SetDescription (ODLinkDescription *desc)

Parameters

desc (ODLinkDescription *) - input

  A string containing part-specific information to be published.

Returns

None.

Remarks

The part description could include information such as the part kind, name, and type, and more specific information as to how the linked content is being used in the destination part. This method can be called multiple times after the link has been established. With each call, the new comment replaces the old one.

### SetSourcePart

This method establishes the source part that is to maintain this link-source object.

Signature

    void SetSourcePart (ODStorageUnit *sourcePartSU)

Parameters

sourcePartSU (ODStorageUnit *) - input

  A reference to the storage unit for the new source part or kODNULL if the link source no longer references the part's storage unit (that can be undone by calling the part's storage unit).

Returns

None.

Remarks

Both parts and container applications call this method, typically when this link-source object is cloned during data-transfer operations involving linked content.

If the user cuts content from your part that includes a link source, your part relinquishes ownership of the link-source object. If the user subsequently undoes that action, you must call this method to reclaim ownership.

After this method executes successfully, the reference count of the storage unit of the previous source part is decremented and the reference count of the new source part's storage unit is incremented.

### ShowLinkSourceInfo

This method displays the Link Source Info dialog box for this link-source object.

Signature

    ODBoolean ShowLinkSourceInfo (ODFacet facet,
                                  ODUpdateID change,
                                  ODBoolean changesAllowed,
                                  ODLinkInfoResult infoResult)

Parameters

facet (ODFacet) - input

  A reference to the facet displaying the selected link source.

change (ODUpdateID) - input

  The update ID of the source part's source content.

changesAllowed (ODBoolean) - input

  kODTrue if the user may change characteristics of this link-source object, otherwise kODFalse.

infoResult (ODLinkInfoResult) - output

  A structure reflecting the user's selections in the Link Source Info dialog box.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the user cancelled the Link Source Info dialog box.

  kODTrue | User did not cancel the dialog box.
  kODFalse | User cancelled the dialog box.

Remarks

You call this method in your part's HandleEvent method when the user selects the Link Info subitem from the Links item from the Edit menu and the current selection is the border of a link source.

If the change parameter is different from this link-source object's current update ID (as returned by the GetUpdateID method), this link-source object does not have the most recent source content. This situation should occur only if the update mode is manual. In this case, the Update Now button is enabled to allow the user to request the link source to be updated from the source part.

Part viewers (as opposed to part editors) should pass false for the changesAllowed parameter. Changes are disabled automatically if the draft is read only.

The Link Source Info dialog box displays the part kind of the linked data, together with the dates and times of its creation and last update. The dialog box lets the user set the link update mode to automatic (On Save) or manual. The user can also break the link or request an immediate update from the source part to this link-source object.

If the user exits the Link Source dialog box by clicking a button other than Cancel, this method returns true and you should examine the action field of the infoResult output parameter to determine what action to take in response to the user's selections.

If the user cancels the Link Source Info dialog box, this method returns false and you do not need to take any further action.

Exception Handling

kODErrBrokenLink | Internal error; this link-source object disconnect from its destination.
kODErrNullFacetInput | The facet parameter is null.
kODErrNullLinkInfoResultInput | The infoResult parameter is null.

Related Methods

- ODLink::SetDescription (OS/2)
- ODLinkSource::ContentUpdated
- ODLinkSource::GetUpdateID
- ODLinkSource::IsAutoUpdate
- ODLinkSource::SetAutoUpdate

### Unlock

This method unlocks this link-source object, relinquishing access to its content storage unit.

Signature

    void Unlock (ODLinkKey key)

Parameters

key (ODLinkKey) - input

  A valid key obtained by a prior call to the Lock method.

Returns

None.

Remarks

You should call this method as soon as possible after accessing or modifying the content storage unit of this link-source object.

The key parameter should be a valid key obtained by an earlier call to the Lock method. After this method executes successfully, the specified key is no longer valid and access to the link-source object's content is relinquished.

Exception Handling

kODErrInvalidLinkKey | The key parameter is not a valid key for this link-source object.

Related Methods

- ODLinkSource::Lock

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]