home *** CD-ROM | disk | FTP | other *** search
/ The AGA Experience 2 / agavol2.iso / software / utilities / comms / term / extras / hydracom / hydracom-source.lha / Rendezvous.h < prev    next >
C/C++ Source or Header  |  1994-07-03  |  7KB  |  207 lines
  1. /*
  2. **    Rendezvous.h - External program interface for Amiga
  3. **                   telecommunications software
  4. **
  5. **    Written by Olaf Barthel, freely distributable.
  6. */
  7.  
  8.     /* Minimum rendezvous data structure revision. */
  9.  
  10. #define RENDEZVOUS_VERSION    0
  11.  
  12.     /* Returned by rs_Login(). */
  13.  
  14. struct RendezvousData
  15. {
  16.     LONG             rd_Version;        /* Version of this data structure. */
  17.     struct Screen        *rd_Screen;        /* Pointer to terminal screen. */
  18.     struct IOExtSer         rd_ReadRequest,    /* Serial read request. */
  19.                  rd_WriteRequest;    /* Serial write request. */
  20.  
  21.     struct List         rd_UploadList,        /* List of files to upload. */
  22.                  rd_DownloadList,    /* List of files to receive. */
  23.  
  24.                  rd_SentList,        /* List of files sent (uploaded). */
  25.                  rd_ReceivedList;    /* List of files received (downloaded). */
  26.  
  27.     STRPTR             rd_SendPath,        /* Path to look into for files to send. */
  28.                  rd_ReceivePath,    /* Path to place files into when receiving. */
  29.  
  30.                  rd_Options;        /* Protocol options, command line parameters, etc. */
  31. };
  32.  
  33.     /* Rendezvous interface data, this is what FindSemaphore()
  34.      * returns.
  35.      */
  36.  
  37. struct RendezvousSemaphore
  38. {
  39.     struct SignalSemaphore    rs_Semaphore;        /* Link access. */
  40.  
  41.     LONG            rs_Version;        /* Data structure version. */
  42.  
  43.         /* Callback routines follow below. */
  44.  
  45.     struct RendezvousData *    (* __asm rs_Login)(register __a0 struct MsgPort *ReadPort,register __a1 struct MsgPort *WritePort,register __a2 struct TagItem *TagList);
  46.     VOID            (* __asm rs_Logoff)(register __a0 struct RendezvousData *Data);
  47.     struct Node *        (* __asm rs_NewNode)(register __a0 STRPTR Name);
  48. };
  49.  
  50. /***********************************************************************
  51.  
  52. About the rendezvous interface
  53. ==============================
  54. `term' 4.0 provides an interface for other client program to gain control
  55. over the serial driver. In order to do so, the following needs to be done
  56. (code fragment follows):
  57.  
  58.    struct RendezvousSemaphore *Semaphore;
  59.  
  60.    Forbid();
  61.  
  62.       // Find the access semaphore, note that "TERM" can be any
  63.       // other interface name, provided it is unique.
  64.  
  65.    if(Semaphore = (struct RendezvousSemaphore *)FindSemaphore("TERM"))
  66.    {
  67.       ObtainSemaphore(Semaphore);
  68.  
  69.       Permit();
  70.    }
  71.    else
  72.       Permit();
  73.  
  74. Once the client has acquired the RendezvousSemaphore it can access the
  75. data attached to it. Please note that the contents of the
  76. RendezvousSemaphore are read-only. The rs_Version entry indicates which
  77. entries and routines are available in this data structure. Please note
  78. that the data structure may grow in the future.
  79.  
  80. To link to to `term', call the rs_Login() routine, such as shown
  81. below:
  82.  
  83.    struct MsgPort        *ReadPort,
  84.                          *WritePort;
  85.    struct RendezvousData *Data;
  86.  
  87.    if(ReadPort = CreateMsgPort())
  88.    {
  89.       if(WritePort = CreateMsgPort())
  90.       {
  91.           if(Data = (*Semaphore -> rs_Login)(ReadPort,WritePort,NULL))
  92.           {
  93.              // Work with it.
  94.  
  95.              :
  96.              :
  97.              :
  98.  
  99. Make sure that you get what you want, rs_Login() may return NULL in case
  100. of failure.
  101.  
  102.  
  103. The RendezvousData structure
  104. ============================
  105. Let's have a look at the contents of the RendezvousData structure:
  106.  
  107. 1. rd_Version [read-only]
  108.  
  109. Just like the RendezvousSemaphore it includes a version entry (rd_Version)
  110. to help you to find out which entries are present and which are not
  111. (remember that this data structure may grow in the future).
  112.  
  113. 2. rd_Screen [read-only]
  114.  
  115. Here you can find a pointer to the screen `term' uses or a NULL in case
  116. `term' could not return a proper address. You can use this screen to
  117. open your windows on it.
  118.  
  119. 3. rd_ReadRequest, rd_WriteRequest
  120.  
  121. These are ready-to-use serial I/O requests for your program. The
  122. rs_Login() call will have placed your ReadPort and WritePort pointers
  123. in these requests for you to use.
  124.  
  125. 4. rd_UploadList
  126.  
  127. This is a standard List with plain Nodes in it. Each node contains the
  128. name of a file to upload. You are requested to process this list if
  129. possible. When you are finished uploading a file, Remove() the
  130. corresponding Node from this list and AddTail() it to the rd_SentList.
  131.  
  132. 5. rd_DownloadList
  133.  
  134. This is another standard Listh with plain Nodes in it. Each of these
  135. nodes contains the name of a file to receive, or to request from the
  136. remote. You are requested to process this list if possible. When you
  137. are finished receiving a file whose name could be found in the list,
  138. Remove() the corresponding Node from this list and AddTail() it to
  139. the rd_ReceivedList.
  140.  
  141. 6. rd_SentList
  142.  
  143. After having sent a file whose name could not be found on the
  144. rd_UploadList, allocate a Node using the rs_NewNode() call with
  145. the name of the file as the parameter and AddTail() it to this list.
  146.  
  147. 7. rd_ReceivedList
  148.  
  149. After having received a file whose name could not be found on the
  150. rd_DownloadList, allocate a Node using the rs_NewNode() call with
  151. the name of the file as the parameter and AddTail() it to this list.
  152.  
  153. 8. rd_SendPath [read-only]
  154.  
  155. This gives the name of the directory to look for files to send. Please
  156. note that this pointer may be NULL, ignore it in this case.
  157.  
  158. 9. rd_ReceivePath [read-only]
  159.  
  160. This gives the name of the directory to receive files into. Please
  161. note that this pointer may be NULL, ignore it in this case.
  162.  
  163. 10. rd_Options [read-only]
  164.  
  165. You can find a list of options or command line parameters here. `term'
  166. may place special data for you here. Please note that this pointer
  167. may be NULL, ignore it in this case.
  168.  
  169.  
  170. How to disconnect
  171. =================
  172. When the client is finished with whatever service it could provide,
  173. it must make sure that no read or write request is still pending.
  174. If the client made any changes to the serial parameters they should be
  175. restored to their original state. Finally, the client must call
  176. rs_Logoff() and release the semaphore as illustrated below:
  177.  
  178.    (*Semaphore -> rs_Logoff)(Data);
  179.  
  180.    ReleaseSemaphore((struct SignalSemaphore *)Semaphore);
  181.  
  182. After rs_Logoff() is called no further references may be made to the
  183. RendezvousData structure. You may still call the rs_Login()+rs_Logoff()
  184. pair as many times you like until you let go of the RendezvousSemaphore.
  185.  
  186.  
  187. Future extensions & author's address
  188. ====================================
  189. The rendezvous interface may grow in the future. If you need to make
  190. changes to the specifications or add extensions you should register
  191. them with me. If you need more information on how to implement a
  192. client or a host interface feel free to ask.
  193.  
  194. My postal address is:
  195.  
  196.    Olaf Barthel
  197.    Brabeckstrasse 35
  198.    D-30559 Hannover
  199.  
  200.    Federal Republic of Germany
  201.  
  202. eMail:
  203.  
  204.    olsen@sourcery.han.de
  205.  
  206. ***********************************************************************/
  207.