home *** CD-ROM | disk | FTP | other *** search
/ Millennium Time Capsule / AC2000.BIN / disks / ac9_disk / dhst4lc / dhst4lc.txt < prev   
Text File  |  1998-03-08  |  5KB  |  210 lines
  1.                    The English documentation to the
  2.  
  3.                       Document History Protocol
  4.  
  5.                              Revision 01
  6.                                08.03.97
  7.  
  8.                                   by
  9.  
  10.                              Mark Wherry
  11.  
  12.                    mark.wherry@mail.inxpress.co.uk
  13.  
  14.  
  15.  
  16. Contents
  17. ========
  18.  
  19.  1  Introduction
  20.  
  21.  2  Document-History-Protocol
  22.  
  23.  3  Usage
  24.  
  25.  4  DHST_Add()
  26.  
  27.  5  Contact Me
  28.  
  29.  6  Legal
  30.  
  31.  
  32.  
  33. 1  Introduction
  34. ***************
  35.  
  36. There are so many great innovations on the Atari platform to put more
  37. and more features at the user's disposal, making life easier. As
  38. programmers, most of us can't wait to add support for these new tricks
  39. in our own programs. However there are two obstacles that often stand
  40. in the way.
  41.  
  42. Most of the documentation for modern enhancements remains in German,
  43. and any code available is usually written for Pure-C.
  44.  
  45. To try and make life easier for the programmer, here is my attempt at
  46. a translation of the Document History Protocol specification, and a
  47. binding for use with Lattice C5.
  48.  
  49.  
  50.  
  51. 2  Document-History-Protocol
  52. ****************************
  53.  
  54. The aim of the Document History (DHST) protocol, is to maintain a
  55. global list of the last documents to be used on the operating system.
  56. These files are then made accessable from a uniform place (e.g. The
  57. Start-Me-Up menu) to make retrieval quicker and easier for the user.
  58.  
  59. Here is the structure and values in C notation:
  60.  
  61. ----------------------------------------------------------------------
  62.  
  63. #define DHST_ADD 0xdadd
  64. #define DHST_ACK 0xdade
  65.  
  66. typedef struct{
  67.   char *appname,
  68.        *apppath,
  69.        *docname,
  70.        *docpath;
  71. }DHSTINFO;
  72.  
  73. ----------------------------------------------------------------------
  74.  
  75. Every time the user opens a file, the application should search for
  76. the cookie 'DHST'. If this is available, the lower word of the cookie
  77. value should hold the AES-ID of the DHST server (e.g. Start-Me-Up) to
  78. send the DHST_ADD message to.
  79.  
  80. The application places a DHSTINFO-structure in global memory and fills
  81. it with the corresponding data:
  82.  
  83.  appname:     The  name of the application
  84.               (e.g. "Texel")
  85.  
  86.  apppath:     The absolute path of the  application
  87.               (e.g. "c:\program\texel.app")
  88.  
  89.  docname:     The name of the document
  90.               (e.g. "balmer.txl")
  91.  
  92.  docpath:     The absolute path of the document
  93.               (e.B. "d:\data\balmer.txl")
  94.  
  95. The application then sends the DHST-Server the following message:
  96.  
  97. ----------------------------------------------------------------------
  98.  
  99. msg[0]         DHST_ADD
  100. msg[1]         ap_id
  101. msg[2]         0
  102. msg[3]+msg[4]  Pointer to the DHSTINFO-structure
  103. msg[5]         0
  104. msg[6]         0
  105. msg[7]         0
  106.  
  107. ----------------------------------------------------------------------
  108.  
  109. On receiving the following message, the application can then release
  110. the global memory used:
  111.  
  112. ----------------------------------------------------------------------
  113.  
  114. msg[0]         DHST_ACK
  115. msg[1]         ap_id
  116. msg[2]         0
  117. msg[3]+msg[4]  Pointer to DHSTINFO-structure
  118.                (As passed with DHST_ADD)
  119. msg[5]         0
  120. msg[6]         0
  121. msg[7]         0=error(s), else: OK
  122.  
  123. ----------------------------------------------------------------------
  124.  
  125.  
  126.  
  127. 3  Usage
  128. ********
  129.  
  130. In order to use my binding in your program, do the following...
  131.  
  132. · Link the file "DHST4LC.O" into your code, via the project manager.
  133.  
  134. · Copy the file "DHST4LC.H" into your headers folder.
  135.  
  136. · Add the line "#include <DHST4LC.H>" into your other includes.
  137.  
  138. And finally,
  139.  
  140. · Add a DHST_Add() call whenever a user opens an existing file, or
  141. creates a new one.
  142.  
  143.  
  144.  
  145. 4  DHST_Add()
  146. *************
  147.  
  148. *_Synopsis_*
  149.  
  150. retval = DHST_Add(app_id, app_name, app_path, doc_name, doc_path);
  151.  
  152. int retval;      Return value
  153. int app_id;      AES id of the program calling DHST_Add()
  154. char *app_name,  Name of the application
  155.      *app_path,  Absolute path of the application
  156.      *doc_name,  Name of the document
  157.      *doc_path;  Absolute path of the document
  158.  
  159. *_Description_*
  160.  
  161. Formats the passed values into a DHSTINFO-structure and sends a
  162. DHST_ADD AES message to the DHST server.
  163.  
  164. *_Returns_*
  165.  
  166. This function returns 1 if everything was OK, or 0 if an error
  167. occured.
  168.  
  169.  
  170.  
  171. 5  Contact Me
  172. *************
  173.  
  174. If you have any suggestions, criticisms, want to beta test for me, or
  175. just want a chat- here's my address:
  176.  
  177. Snail mail: 4 Fernpark Close,
  178.             Topsham Road,
  179.             Exeter,
  180.             Devon,
  181.             EX2 6AW
  182.             England
  183.  
  184. Email: mark.wherry@mail.inxpress.co.uk
  185.  
  186.  
  187.  
  188. 6  Legal
  189. ********
  190.  
  191. I do hate this bit, but everyone else seems to do it these days, so...
  192.  
  193. _Disclaimer_
  194.  
  195. The user uses this distribution at their own risk! I, or anyone
  196. mentioned in this document, are not responsible for any damages you
  197. may suffer through the use of the files in this distribution.
  198.  
  199. _Copyright_
  200.  
  201. You may freely copy this distribution so long as the contents are not
  202. altered in any way. The Document History Protocol and the original
  203. specification is the work of Thomas Much. This distribution and
  204. translation is seperate, and the work of Mark Wherry.
  205.  
  206. Whew ;-)
  207.  
  208.  
  209.  
  210.