Programming Reference: ODLink

# Programming Reference

## ODLink

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

Class hierarchy

    SOMObject
       ODObject
          ODRefCntObject
             ODPersistentObject
                ODBaseLink
                   ODLink

Description

An object of the ODLink class represents the destinations of an OpenDoc link. Instances of this class 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) in such a way that the destination data can be updated manually or automatically when the source data changes. A typical example of linking allows the user to paste a spreadsheet graph into a financial report in such a way that subsequent changes to the spreadsheet are automatically 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.

When the user requests a link, the following events occur:

- 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. The source part may refuse this request, in which case the link cannot be created; normally, however, the source part would refuse only in the event of an error.

  If the source part is in a different document, the link manager creates a cross-document link.

- If the link-source object was created successfully, the draft's AcquireLink method returns a link object to the destination part.

Every link-source object 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 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.

The destination part reads link data from a link object's content storage unit. Because source and destination parts may attempt to access a link simultaneously, parts must acquire a lock before they can access the content storage unit. You can lock a link object by calling its Lock method; you can then obtain a reference to the link object's content storage unit by calling its GetContentStorageUnit method. You must not cache this storage unit; instead, you must call the GetContentStorageUnit method when you need to access the storage unit.

A destination part can register itself for automatic notification of updates by calling the RegisterDependent method of the link object. When the link-source object sends updates to the link object, the link object calls the LinkUpdated method of each of its registered destination parts to notify those parts to read the new data from the link object's content storage unit.

A destination part is responsible for updating its destination content from the link object. If your part is the destination part of a link, its LinkUpdated method should read data from the link object's content storage unit and use the data to update its destination content. In addition, after your part displays the Show Link Destination Info dialog box, it should update its destination content if the user exits the dialog box by clicking the Update Now button.

Each link destination tracks a single link source, but there can be several link destinations for any given link source. Within a given draft, a single link object is associated with each link-source object, even if the source is linked to multiple destinations in the draft; all destinations in the draft share this link object. For this reason, a part that maintains two or more destinations of a given link source must be careful to register only once with the corresponding link object.

A destination part's registration with a link is not permanent; the part should reregister when it is recreated from its stored data if the destination content is visible or if it could affect the layout of the part. A destination part may explicitly unregister itself from a link by calling the UnregisterDependent method of the link object. A destination part with a single destination for a particular link source should unregister when the user breaks the link at the destination, when the linked content is deleted, or when the user changes the destination from automatic to manual updating. A destination part with multiple destinations of the same link source should unregister in the same situations, provided that none of the other destinations gets updates automatically.

If your part contains a link destination, 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 Show Links setting of the Document Info dialog box, you must show the border of the links destination when you draw. You can check whether to show links by calling the window's ShouldShowLinks method before drawing your part's content.

For further information on the implementation of OpenDoc links, see the descriptions of the companion classes ODLinkSource and ODLinkSpec as well as the chapter on data transfer in the OpenDoc Programming Guide.

Methods

The methods defined for the ODLink class include:

- GetChangeTime
- GetContentStorageUnit
- GetDescription (OS/2)
- GetUpdateID
- IsRegistered (OS/2)
- Lock
- RegisterDependent
- SetDescription (OS/2)
- ShowLinkDestinationInfo
- ShowSourceContent
- Unlock
- UnregisterDependent

Overridden methods | There are no methods overridden by the ODLink class.

### GetChangeTime

This method returns the time of the last update to the link-source content.

Signature

    ODTime GetChangeTime ()

Parameters

None.

Returns

rv (ODTime) - returns

  The time when the link-source content was last updated.

### GetContentStorageUnit

This method returns a reference to the storage unit containing the content of this link 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 object's content storage unit.

Remarks

The key parameter ensures thread safety. Before calling this method, you must call this link object's Lock method to obtain this key. The returned storage unit remains valid until the key is relinquished by the Unlock method.

You can read and copy but should not change the data in the returned content storage unit. The link 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; instead, you must call this method when you need to access the content storage unit.

Exception Handling

kODErrBrokenLink | Internal error; the link source is disconnected from its destinations.
kODErrInvalidLinkKey | The key parameter is not a valid key for this link.

### GetDescription (OS/2)

This method is called by the destination part to get the link's description.

Signature

    void GetDescription (ODLinkDescription *Desc)

Parameters

Desc (ODLinkDescription *) - output

  A string containing a comment describing part-specific information.

Returns

None.

Remarks

The part description could include information such as the part kind, name, or type, or 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 link-source content.

Signature

    ODUpdateID GetUpdateID ()

Parameters

None.

Returns

rv (ODUpdateID) - returns

  The current update ID of the link-source content.

Remarks

If your part contains a destination of this link, you can call this method to determine the current version of the content of the link-source object. You can compare the returned update ID with a previously saved ID to establish whether the source content has been modified since you last read it. 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.

You can arrange for your part to receive automatic notification of content updates by calling the RegisterDependent method.

Exception Handling

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

Related Methods

- ODLink::RegisterDependent
- ODLinkSource::ContentUpdated

### IsRegistered (OS/2)

This method indicates whether the part is registered with the link object using the RegisterDependent method.

Signature

    ODBoolean IsRegistered ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the part is registered with the link object.

  kODTrue | The part is registered with the link object.
  kODFalse | The part is not registered with the link object.

### Lock

This method locks this link object, ensuring exclusive, read-only 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 not granted, this value is 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 can read the link data. This method grants read-only access; a destination part cannot modify a link's content.

A link may be locked by only one object at a time; nested calls to the Lock method deny access.

While your part has the link locked, you must pass the key returned in the key output parameter to all methods that access the link. When you are finished using the link, you must pass this key to the Unlock method to unlock the link.

Exception Handling

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

Related Methods

- ODLink::GetContentStorageUnit
- ODLink::Unlock

### RegisterDependent

This method puts the specified destination part on the list of parts to be notified when the link is updated.

Signature

    void RegisterDependent (ODPart *clientPart,
                            ODUpdateID id)

Parameters

clientPart (ODPart *) - input

  A reference to the destination part wishing to be notified of changes to the content of the link source.

id (ODUpdateID) - input

  The update ID of the content the specified part last read from the link source. This parameter can also be set to the following value:

  kODUnknownUpdate | The part does not keep track of link change identifications. Setting this value ensures that your part's LinkUpdated method is called.

Returns

None.

Remarks

If the your part is a destination of this link, you can call this method to register your part as a dependent of this link object. Dependent parts receive automatic notification of any changes to this link's content. You can remove your part from the list of dependents by calling the UnregisterDependent method.

If the link's current update ID differs from the id parameter, OpenDoc immediately calls the specified client part's LinkUpdated method. You should pass the constant kODUnknownUpdate as the value of the id parameter when the link is first created; doing so ensures that your part's LinkUpdated method is called.

Note:

> You should not call this method if your part is already a registered dependent of this link object, for example, because your part contains another destination of the link source corresponding to this link object.

Exception Handling

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

Related Methods

- ODLink::GetUpdateID
- ODLink::UnregisterDependent
- ODPart::LinkUpdated

### SetDescription (OS/2)

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

Signature

    void SetDescription (ODLinkDescription *Desc)

Parameters

Desc (ODLinkDescription *) - input

  A string containing a comment describing part-specific information which the write of the part containing the link would like to publish.

Returns

None.

Remarks

The part description could include information such as the part kind, name, or type, or 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, and each time, the new comment replaces the old one.

### ShowLinkDestinationInfo

This method displays the Link Destination Info dialog box for this link object.

Signature

    ODBoolean ShowLinkDestinationInfo (ODFacet facet,
                                       ODLinkInfo info,
                                       ODLinkInfoResult infoResult)

Parameters

facet (ODFacet) - input

  A reference to the facet displaying the selected link destination.

info (ODLinkInfo) - input

  A structure containing link destination information.

infoResult ( ODLinkInfoResult) - output

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

Returns

rv (ODBoolean) - returns

  A flag indicating whether you exited the dialog box with a button other than cancel.

  kODTrue | Exited with a button other than cancel.
  kODFalse | Exited with the cancel button.

Remarks

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

The Link Destination 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 or manual. The user can also break the link, request an immediate update from the link data, or display the link source for editing.

If the user exits the Link Destination Info 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 dialog box, this method returns false and you do not need to take any further action.

Exception Handling

kODErrBrokenLink | Internal error; the link-source object disconnected from its destination.
kODErrNullFacetInput | The facet parameter is null.
kODErrNullLinkInfoInput | The info parameter is null.
kODErrNullLinkInfoResultInput | The infoResult parameter is null.

Related Methods

- ODLink::RegisterDependent
- ODLink::ShowSourceContent
- ODLink::UnregisterDependent
- ODLinkSource::ShowLinkSourceInfo

### ShowSourceContent

This method requests the source part of the link to make the source content visible.

Signature

    void ShowSourceContent ()

Parameters

None.

Returns

None.

Remarks

This method causes the source part's RevealLink method to be called, making the source content visible.

If this method returns an exception, you should display an alert message informing the user that the link-source content could not be shown.

Exception Handling

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

This method may also return exceptions that were raised by the part's RevealLink method.

Related Methods

- ODPart::RevealLink
- ODPart::EditInLinkAttempted

### Unlock

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

Signature

    void Unlock (ODLinkKey key)

Parameters

key (ODLinkKey) - input

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

Returns

None.

Remarks

You should call this method as soon as possible after accessing the content storage unit of this link 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's content is relinquished.

Exception Handling

kODErrBrokenLink | Internal error; the link-source object is disconnected from its destinations.
kODErrInvalidLinkKey | The key parameter is not a valid key for this link.

Related Methods

- ODLink::Lock

### UnregisterDependent

This method removes the previously registered destination part from the list of parts to be notified when the link is updated.

Signature

    void UnregisterDependent (ODPart *clientPart)

Parameters

clientPart (ODPart *) - input

  A reference to a destination part to be unregistered.

Returns

None.

Remarks

If your part is a destination of this link, you can call this method to unregister your part as a dependent. Dependent parts receive automatic notification of any changes to the link's content. You can reregister your part by calling the RegisterDependent method.

The UnregisterDependent method returns without error if the specified destination part was not previously registered as a dependent of this link.

Related Methods

- ODLink::RegisterDependent

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