Programming Reference: ODLinkSpec

# Programming Reference

## ODLinkSpec

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

Class hierarchy

    SOMObject
        ODObject
            ODBaseLinkSpec
                ODLinkSpec

Description

An object of the ODLinkSpec class advertises a part's ability to create a link to the data it is transferring.

A link specification is a signal that a link can be made from content in a specified source part. The link specification remains valid as long as its source part exists and the document containing it remains opened. After the document is closed, the link specification becomes meaningless.

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 by calling its draft's CreateLinkSpec method, passing as parameters a reference to itself and data sufficient to enable the source part to identify the selected content. The data in a link specification is private to the source part; it is returned to the source part if the part's CreateLink method is called to create a link. Because the link specification is valid only during the lifetime of its source part, the data can contain pointers to information maintained by the part.

A link specification provides methods for writing or reading itself to and from a focused storage unit. In addition to writing content to the storage unit of the data-transfer object (clipboard or drag-and-drop object), the source part calls the link specification's WriteLinkSpec method to write the link specification to the kODPropLinkSpec property.

For a paste or drop, the destination part creates an empty link specification by calling the draft's CreateLinkSpec method, passing null for the source part and data parameters. The destination part calls the ReadLinkSpec method of the empty link specification to read from the kODPropLinkSpec property of the content storage unit. The destination part then creates the link by passing the link specification to its draft's AcquireLink method, which in turn passes the link specification to the source part's CreateLink method.

When the source part writes a link specification to the clipboard, it should save the clipboard's current update ID, as returned by the clipboard's GetUpdateID method. The part must remove the link specification from the clipboard if any of the following conditions is true:

- It becomes infeasible to create the link, for example, because the potential source content is deleted or modified.

- The part's Release method is called.

The source part can check the clipboard update ID and compare it with the saved ID to determine whether its content is still on the clipboard.

For further information on the clipboard and drag-and-drop object, see the descriptions of the classes ODClipboard and ODDragAndDrop. For further information on the implementation of OpenDoc links, see the descriptions for the classes "ODLink" and ODLinkSource and the chapter on the data transfer in the OpenDoc Programming Guide.

Methods

The methods defined by the ODLinkSpec class include:

- ReadLinkSpec
- WriteLinkSpec

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

### ReadLinkSpec

This method initializes this empty link specification by reading its data from the specified focused storage unit.

Signature

    void ReadLinkSpec (ODStorageUnit *su)

Parameters

su (ODStorageUnit *) - input

  A reference to the storage unit whose focused value contains the link-specification value.

Returns

None.

Remarks

If your part is a destination part, you create an empty link specification by calling the draft's CreateLinkSpec method, passing null for the source part and data parameters. Then, call the empty link specification's ReadLinkSpec method to initialize the link specification from data in the content storage unit of the clipboard or the drag-and-drop object. The storage unit should be focused on the kODPropLinkSpec property.

Exception Handling

kODErrCorruptLinkSpecValue | The focused storage unit contains an invalid link-specification.
kODErrNoLinkSpecValue | The focused property does not contain a link-specification value.
kODErrOutOfMemory | There is not enough memory to read the link specification.
kODErrUnknownLinkSpecVersion | The link-specification version is not recognized.

Related Methods

- ODDraft::CreateLinkSpec
- ODLinkSpec::WriteLinkSpec

### WriteLinkSpec

This method writes the data for this link specification into the specified prefocused storage unit.

Signature

    void WriteLinkSpec (ODStorageUnit *su)

Parameters

su (ODStorageUnit *) - input

  A reference to the storage unit where the link specification data is to be written.

Returns

None.

Remarks

If your part is a source part that supports linking, you call this method to write a link specification to the content storage unit of the clipboard or the drag-and-drop object. The storage unit should be focused on the kODPropLinkSpec property. This method writes the link specification to the value of type kODLinkSpec in the focused property, replacing any link specification that was previously stored in that value or creating the value if it does not already exist.

Exception Handling

kODErrOutOfMemory | There is not enough memory to write the link specification.

Related Methods

- ODLinkSpec::ReadLinkSpec

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