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