home *** CD-ROM | disk | FTP | other *** search
/ The Developer Connection…ice Driver Kit for OS/2 3 / DEV3-D1.ISO / source / bento / headers / link.h < prev    next >
Encoding:
C/C++ Source or Header  |  1994-03-02  |  6.3 KB  |  189 lines
  1. /*
  2.     File:        Link.h
  3.  
  4.     Contains:    The abstract XMPLink class
  5.  
  6.     Written by:    Nick Pilch & Craig Carper
  7.  
  8.     Copyright:    ⌐ 1993 by Apple Computer, Inc., all rights reserved.
  9.  
  10.     Change History (most recent first):
  11.  
  12.         <11>     1/21/94    CC        Moved some fields and methods into
  13.                                     LinkSrc.h.
  14.         <10>     1/14/94    CC        Added Lock(), Unlock(), GetTimeStamp(),
  15.                                     GetStatus(), SetAutoExport(),
  16.                                     IsAutoExport(), Export(),
  17.                                     ShowSourceContent(), type XMPLinkKey; added
  18.                                     key parameter to various routines.
  19.          <9>    12/22/93    CC        Added GetContentStorageUnit(); use
  20.                                     XMPVMethod for public methods.
  21.          <8>    12/16/93    CC        Removed useless overrides of GetID() and
  22.                                     GetStorageUnit().
  23.          <7>    12/14/93    Té        InitLink changes.  Internalize, Initialize
  24.                                     went away.
  25.          <6>     9/29/93    VL        Added InitializePersistent.
  26.          <5>      7/1/93    NP        Abstract/Concrete breakout.
  27.          <4>     4/28/93    NP        File name changes.
  28.          <3>     4/21/93    NP        Added Initialize member.
  29.          <2>     4/13/93    NP        Made to conform to new standards.
  30.          <1>     4/13/93    NP        first checked in
  31.  
  32.     To Do:
  33. */
  34.  
  35. #ifndef _LINK_
  36. #define _LINK_
  37.  
  38. #ifndef _PLFMDEF_
  39. #include "PlfmDef.h"
  40. #endif
  41.  
  42. #ifndef _PSTOBJ_
  43. #include "PstObj.h"
  44. #endif
  45.  
  46. //==============================================================================
  47. // Theory of Operation
  48. //==============================================================================
  49.  
  50. /*
  51.     This class is used to represent the destination side of OpenDoc links.
  52.     XMPDrafts create and own these links. The source XMPPart will ask the draft
  53.     to create an XMPLinkSource and an XMPLink pair, and return the XMPLink
  54.     object to the the destination part.  The destination part uses the XMPLink
  55.     object to extract the contents of the link.
  56. */
  57.  
  58. //==============================================================================
  59. // Scalar types defined in this interface
  60. //==============================================================================
  61. typedef XMPULong XMPLinkKey;
  62.  
  63. //==============================================================================
  64. // Classes defined in this interface
  65. //==============================================================================
  66.  
  67. class XMPAbsLink;
  68.  
  69. //==============================================================================
  70. // Classes used by this interface
  71. //==============================================================================
  72.  
  73. class XMPPart;
  74. class XMPStorageUnit;
  75.  
  76. //==============================================================================
  77. // XMPLink
  78. //==============================================================================
  79.  
  80. class XMPAbsLink : public XMPPersistentObject
  81. {
  82.   public:
  83.  
  84.     XMPVMethod XMPBoolean Lock(XMPULong wait, XMPLinkKey* key)
  85.         = 0;
  86.  
  87.         // Acquire exclusive access to the content storage unit of the link
  88.         // for the current thread. The value kXMPTrue is returned if the lock is
  89.         // granted; the key argument is set to a valid link key.  Access is
  90.         // granted if the current thread already holds the lock.  Nested calls
  91.         // to Lock must be balanced by an equal number of calls to Unlock to 
  92.         // relinquish the lock.
  93.  
  94.     XMPVMethod void Unlock(XMPLinkKey key)
  95.         =0;
  96.         
  97.         // Relinquish exclusive access to the content storage unit of the link.
  98.         // The argument should be a non-zero key returned by Lock.
  99.  
  100.     XMPVMethod XMPStorageUnit* GetContentStorageUnit(XMPLinkKey key)
  101.         = 0;
  102.  
  103.         // used by destination parts to get the storage unit
  104.         //  containing the contents of the link.  The key parameter
  105.         //  should be obtained by aquiring the lock for this thread. 
  106.         //  formerly named: GetStorageUnit
  107.  
  108.     XMPVMethod void RegisterDependent(XMPPart* clientPart, XMPChangeID id)
  109.         = 0;
  110.  
  111.         // used by the destination to inform the link of its interest in the
  112.         //  contents of the link. The part╒s LinkUpdated() method is called
  113.         //  immediately if the link╒s change id differs from the argument.
  114.         //  The constant kChangeUnknown may be supplied if the part does not
  115.         //  keep track of link change ids.
  116.         //  formerly named: Notify
  117.         
  118.     XMPVMethod void UnregisterDependent(XMPPart* clientPart)
  119.         = 0;
  120.  
  121.         // unregister dependent part previously registered with RegisterDependent.
  122.         
  123.     XMPVMethod XMPChangeID GetChangeID()
  124.         =0;
  125.  
  126.         // Returns the change id of the link content.  Can be used by destinations
  127.         //  to determine when new data is available.  The returned value should be
  128.         //  tested for equality only, as there is no implicit ordering of change ids.
  129.  
  130.     XMPVMethod XMPError GetStatus()
  131.         = 0;
  132.  
  133.         // Returns the status of the link.  A non-zero value indicates a non-fatal
  134.         // problem which the part may ignore or bring to the user╒s attention.
  135.         // The most common problem is a broken cross-document destination.
  136.         // This situation may be temporary if the source document re-establishes
  137.         // the cross-document link.
  138.  
  139.     XMPVMethod void ShowSourceContent()
  140.         = 0;
  141.  
  142.         // Causes the source part of the link to become active, makes the source content
  143.         // visible, and displays the link border.  Throws an exception if the source
  144.         // part of the link cannot be located, or if the link has been broken at the
  145.         // source.
  146.  
  147.     //---------------------------------
  148.     // For XMPLinkSource
  149.  
  150.     XMPVMethod void UpdateDependents(XMPChangeID id)
  151.         = 0;
  152.         
  153.         // Notify dependent parts of a change to link contents.
  154.  
  155.     //-------------------------------------------------------------------------
  156.     // From Memory protocol
  157.     //-------------------------------------------------------------------------
  158.     
  159.     XMPVMethod XMPSize Purge(XMPSize size)
  160.         = 0;
  161.  
  162.         // Gets rid of any unnecessary memory by purging memory blocks
  163.         //    or flushing structures out to disk
  164.                     
  165.     //-------------------------------------------------------------------------
  166.     // From Persistent Object protocol
  167.     //-------------------------------------------------------------------------
  168.  
  169.     XMPVMethod void Externalize()
  170.         = 0;
  171.  
  172.         // used by the Draft to get the link to externalize the necessary
  173.         //    parts of its persistent store.
  174.     
  175.     //-------------------------------------------------------------------------
  176.     // constructors/destructors
  177.     //-------------------------------------------------------------------------
  178.  
  179.     XMPAbsLink(){}
  180.  
  181.     XMPVMethod    ~XMPAbsLink() {}
  182. };
  183.  
  184. #ifndef _LINKM_
  185. #include "LinkM.h"
  186. #endif
  187.  
  188. #endif // _LINK_
  189.