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:
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: |
Overridden methods | There are no methods overridden by the ODLink class. |
This method returns the time of the last update to the link-source content.
Signature
ODTime GetChangeTime () |
Parameters
None.
Returns
This method returns a reference to the storage unit containing the content of this link object.
Signature
ODStorageUnit *GetContentStorageUnit (ODLinkKey key) |
Parameters
Returns
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. |
This method is called by the destination part to get the link's description.
Signature
void GetDescription (ODLinkDescription *Desc) |
Parameters
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 returns the update ID that uniquely identifies the current generation or version of link-source content.
Signature
ODUpdateID GetUpdateID () |
Parameters
None.
Returns
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
This method indicates whether the part is registered with the link object using the RegisterDependent method.
Signature
ODBoolean IsRegistered () |
Parameters
None.
Returns
| kODTrue | The part is registered with the link object. |
| kODFalse | The part is not registered with the link object. |
This method locks this link object, ensuring exclusive, read-only access to its content storage unit.
Signature
ODBoolean Lock (ODULong wait,
ODLinkKey *key)
|
Parameters
Returns
| 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
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
| 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
This method is called by the destination part to set the link's description.
Signature
void SetDescription (ODLinkDescription *Desc) |
Parameters
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.
This method displays the Link Destination Info dialog box for this link object.
Signature
ODBoolean ShowLinkDestinationInfo (ODFacet facet,
ODLinkInfo info,
ODLinkInfoResult infoResult)
|
Parameters
Returns
| 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
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
This method unlocks this link object, relinquishing access to its content storage unit.
Signature
void Unlock (ODLinkKey key) |
Parameters
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
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
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