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. 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.
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: |
Overridden Methods | There are no methods overridden by the ODLinkSource class. |
This method clears the content of this link-source object.
Signature
void Clear (ODUpdateID id,
ODLinkKey key)
|
Parameters
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:
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
This method notifies this link-source object that its content has been updated.
Signature
void ContentUpdated (ODUpdateID id,
ODLinkKey key)
|
Parameters
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:
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
This method returns the time that this link-source object was last updated.
Signature
ODTime GetChangeTime () |
Parameters
None.
Returns
This method returns a reference to the content storage unit for this link-source object.
Signature
ODStorageUnit *GetContentStorageUnit (ODLinkKey key) |
Parameters
Returns
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
This method is called by the source part to get the link-source object's description.
Signature
void GetDescription (ODLinkDescription *desc) |
Parameters
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 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
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
This method indicates whether the link-source object's update mode is automatic.
Signature
ODBoolean IsAutoUpdate () |
Parameters
None.
Returns
| 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
This method locks this link-source object, ensuring exclusive 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 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
This method sets this link-source object's update mode to automatic or manual.
Signature
void SetAutoUpdate (ODBoolean automatic) |
Parameters
| 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
This method is called by the source part to set the link source's description.
Signature
void SetDescription (ODLinkDescription *desc) |
Parameters
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.
This method establishes the source part that is to maintain this link-source object.
Signature
void SetSourcePart (ODStorageUnit *sourcePartSU) |
Parameters
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.
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
Returns
| 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
This method unlocks this link-source 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 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