home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 2 BBS / 02-BBS.zip / FSC.ZIP / FSC-0013.TXT < prev    next >
Text File  |  1987-12-18  |  21KB  |  362 lines
  1. FSC-0013
  2.   
  3.                        A Standard for "Bark" File Requests
  4.                           Draft 3     December 18, 1987
  5.                         Fidgit Greylock, Greylock Software
  6.                                          
  7.                                          
  8.                       Copyright 1987 Greylock Software, Inc.
  9.                                          
  10.                  License to distribute granted exclusively to the
  11.                         International FidoNet Association.
  12.  
  13.  
  14. 1  Introduction
  15.  
  16. 1.1  This Document
  17.  
  18.   This document describes the standard  for "Bark"-type FidoNet  file requests.
  19. It is  based on the  file BARK.DOC by  Thom Henderson,  my own experiences, and
  20. comments from various network developers.   I have attempted to write this file
  21. in the style of the FSC001  document, some references to which are made in this
  22. document.   This  document  assumes that  you have  access to FSC001,  and/or a
  23. general knowledge of FidoNet mail sessions.
  24.   Please send comments to Fidgit Greylock at FidoNet node 1:321/112.
  25.  
  26.  
  27. 1.2  Credits
  28.  
  29.   Thanks to all of the people who answered my questions in NET_DEV, and to Thom
  30. Henderson for the original BARK.DOC.
  31.   Special thanks to Bob Hartman, without whose comments this document would not
  32. be what it is today.
  33.   Portions of this document are reprinted from  "A  Basic FidoNet(tm) Technical
  34. Standard", by Ryugen Fisher, copyright 1987, International FidoNet Association.
  35.    
  36.  
  37.  
  38. 1.3  What are File Requests?
  39.  
  40.   File Requests are a way of requesting that a  specific file be  sent during a
  41. FidoNet mail session.  This has many advantages over simply logging on to a BBS
  42. and downloading a file:  you need not be  a validated user;  you  don't have to
  43. spend time searching  for the file  on the BBS;  and you can  schedule the file
  44. request to take place at any time without your being near your computer.
  45.   There are two commonly  used types of file  requests on FidoNet  today: WaZOO
  46. and Bark requests.   WaZOO requests are used  by Opus and BinkleyTerm,  and are
  47. not documented here.   See the file WZ_REQ.DOC by Wynn Wagner for a description
  48. of these.   Bark requests are somewhat  more complicated,  and are supported by
  49. most mailers,  including SEAdog,  Dutchie, BinkleyTerm, and to a certain extent
  50. Opus.  This document describes how to implement Bark-type file requests.
  51.   Bark file requests are an extension of the network mail session  as described
  52. in FSC001.
  53.  
  54.  
  55. 1.4  Terms Used in this Document
  56.  
  57.   The diagrams and notations used in this document  are the same  as those used
  58. in the FSC001 document.  Please see FSC001 for a description of these.
  59.   
  60.   There is one extra terminal used in this notation:
  61.   
  62.   someName<max> - String of up to max chars, NOT null terminated
  63.  
  64.  
  65. 2  Performing File Requests
  66.  
  67. 2.1  Introduction
  68.  
  69.   Originating a Bark request is basically a matter of transmitting a data block
  70. containing  a filename;  a  date (used  for update requests);  and optionally a
  71. password, and then using Telink or SEAlink to receive the file.
  72.   Honoring an  incoming file request is  essentially the above  procedure, from
  73. the other side.   It's a matter of prompting for a data block; receiving a data
  74. block; finding the file; and transmitting it using Telink or SEAlink.
  75.   Update requests are the  same as file  requests,  with one exception.  On the
  76. end honoring the file request,  if the date in the data block (described below)
  77. is greater than or equal to the  date of the actual  file on the  honoring end,
  78. the file will not be sent.   The requestor should set  the date to the  date of
  79. the actual file on its own end if an update request is desired.
  80.  
  81.  
  82. 2.2  The Data Block
  83.  
  84. 2.2.1  Description
  85.  
  86.   The data  block in  a Bark  request is  a variable-sized  block  containing a
  87. header,  a  filename,  a date (which  is used only  for update requests -  in a
  88. normal file request it's 0) and an optional password.
  89.   Note that some systems will send a password in the data block even if none is
  90. needed.  Incoming passwords should be ignored unless the other system is trying
  91. to request a passworded file.
  92.   When receiving a data block,  the ETX may be used to determine the end of the
  93. block.
  94.   Below is a diagram of the data block in the tradition of FSC001.
  95.  
  96.  
  97. 2.2.2  Diagram
  98.  
  99.   
  100.   Bark File Request Data Block
  101.   
  102.   
  103.       .------------------------------------.
  104.   0   |             ACK - 06H              |
  105.       +------------------------------------+
  106.   1   |              Filename              |
  107.       +------------------------------------+
  108.   n   |            Space - 20H             |
  109.       +------------------------------------+
  110.   n   |                Date                |
  111.       +------------------------------------+
  112.   n   |   Space (used only if a password   |
  113.       |            follows)                |
  114.       +------------------------------------+
  115.   n   |        Password (Optional)         |
  116.       +------------------------------------+
  117.   n   |             ETX - 03H              |
  118.       +------------------------------------+
  119.   n   |           CRC Low Byte             |
  120.       +------------------------------------+
  121.   n   |          CRC High Byte             |
  122.       `------------------------------------'
  123.  
  124.  
  125. 2.2.3  Definitions
  126.  
  127.   
  128.   DataBlock (no password) = ACK
  129.                             Filename<12>
  130.                             Space
  131.                             Date<11>
  132.                             ETX
  133.                             CRC
  134.   
  135.   DataBlock (with password) = ACK
  136.                               Filename<12>
  137.                               Space
  138.                               Date<11>
  139.                               Space
  140.                               Password<6|8>
  141.                               ETX
  142.                               CRC
  143.   
  144.   ACK   = 06H       (* Header for file request block *)
  145.   Space = 20H       (* Space character *)
  146.   ETX   = 03H       (* End of block *)
  147.   
  148.   Filename          (* Name of file requested *)
  149.   Date              (* ASCII string; the number of seconds
  150.                        since midnight, January 1, 1970 *)
  151.   Password          (* The password needed to request this
  152.                        file, if any.  Maximum length is 6 for
  153.                        BinkleyTerm and Opus, 8 for SEAdog
  154.                        and Dutchie. *)
  155.   
  156.   CRC = crc[2]      (* CCITT Cyclic Redundancy Check.  The
  157.                        same algorithm as used for XModem
  158.                        CRCs.  The CRC is calculated on
  159.                        all data in the block between but
  160.                        not including the ACK and the ETX *)
  161.   
  162.  
  163.  
  164. 2.3  The Request
  165.  
  166. 2.3.1  Description
  167.  
  168.   File  Requests  are performed at  the end of  a normal  FidoNet mail session.
  169. Below are diagrams detailing a full FidoNet mail session with file requests for
  170. both  the   originator  and  answerer   of  the  session.    The  diagrams  are
  171. self-contained and neither refers to the other;  however,  both refer to states
  172. defined  in  FSC001.   These diagrams  replace  the  corresponding  diagrams in
  173. FSC001.
  174.   Parts of the diagrams below have been reprinted from FSC001.
  175.   Note that you may use SEAlink in place of Telink when sending or  receiving a
  176. file during a file request.
  177.  
  178.  
  179. 2.3.2  Originator Diagram
  180.  
  181.   
  182.   Originator of Mail Session
  183.   
  184.   .-----+----------+-------------------------+-------------------------+-----.
  185.   |State| State    | Predicate(s)            | Action(s)               | Next|
  186.   |  #  | Name     |                         |                         | St  |
  187.   |-----+----------+-------------------------+-------------------------+-----|
  188.   | S0  | SendInit |                         | dial modem              | S1  |
  189.   |-----+----------+-------------------------+-------------------------+-----|
  190.   | S1  | WaitCxD  | 1 carrier detected      | delay 1-5 seconds       | S2  |
  191.   |     |          | 2 busy, etc.            | report no connection    | exit|
  192.   |     |          | 3 voice                 | report no carrier       | exit|
  193.   |     |          | 4 carrier not detected  | report no connection    | exit|
  194.   |     |          |   within 60 seconds     |                         |     |
  195.   |-----+----------+-------------------------+-------------------------+-----|
  196.   | S2  | WhackCRs | 1 over 30 seconds       | report no response <cr> | exit|
  197.   |     |          | 2 ?? <cr>s received     | delay 1 sec             | S3  |
  198.   |     |          | 3 <cr>s not received    | send <cr> <sp> <cr> <sp>| S2  |
  199.   |     |          |                         |   delay ??? secs        |     |
  200.   |-----+----------+-------------------------+-------------------------+-----|
  201.   | S3  | WaitClear| 1 no input for 0.5 secs | send TSYNCH = AEH       | S4  |
  202.   |     |          | 2 over 60 seconds       | hang up, report garbage | exit|
  203.   |     |          |   and line not clear    |                         |     |
  204.   |-----+----------+-------------------------+-------------------------+-----|
  205.   | S4* | SendMail |                         | (XMODEM send packet XS0)| S5  |
  206.   |-----+----------+-------------------------+-------------------------+-----|
  207.   | S5  | CheckMail| 1 XMODEM successful     | (Fido registers success)| S6  |
  208.   |     |          | 2 XMODEM fail or timeout| hang up, report mail bad| exit|
  209.   |-----+----------+-------------------------+-------------------------+-----|
  210.   | S6* | SendFiles|                         | (BATCH send files BS0)  | S7  |
  211.   |-----+----------+-------------------------+-------------------------+-----|
  212.   | S7  | CheckFile| 1 BATCH send successful |                         | S8  |
  213.   |     |          | 2 BATCH send failed     | hang up, rept files fail| exit|
  214.   |-----+----------+-------------------------+-------------------------+-----|
  215.   | S8  | TryPickup| 1 wish to pickup        |                         | S9  |
  216.   |     |          | 2 no desire to pickup   | delay 5 secs            | exit|
  217.   |     |          |                         |   hang up, rept send ok |     |
  218.   |-----+----------+-------------------------+-------------------------+-----|
  219.   | S9  | GetIntent| 1 Received TSYNC        | (receive mail)          | S10 |
  220.   |     |          | 2 Received SYN          | (honor file requests)   | S15 |
  221.   |     |          | 3 Received ENQ          | (request files)         | S18 |
  222.   |     |          | 4 Received 'C' or NAK   | send EOT                | S9  |
  223.   |     |          | 5 Nothing in 60 seconds | note receive failed     | exit|
  224.   |-----+----------+-------------------------+-------------------------+-----|
  225.   | S10 | RecMail  |                         | (XMODEM rec packet XR0) | S11 |
  226.   |-----+----------+-------------------------+-------------------------+-----|
  227.   | S11 | XRecEnd  | 1 XMODEM successful     | delay 1 second          | S12 |
  228.   |     |          |                         |   flush input           |     |
  229.   |     |          | 2 XMODEM failed         | hang up, rept mail fail | exit|
  230.   |-----+----------+-------------------------+-------------------------+-----|
  231.   | S12 | RecFiles |                         | (BATCH rec files BR0)   | S13 |
  232.   |-----+----------+-------------------------+-------------------------+-----|
  233.   | S13 | ChkFiles | 1 BATCH recv successful | delay 2 secs            | S14 |
  234.   |     |          | 2 BATCH recv failed     | hang up, report bad file| exit|
  235.   |-----+----------+-------------------------+-------------------------+-----|
  236.   | S14 | GetIntent| 1 Received SYN          | (honor file requests)   | S15 |
  237.   |     |          | 2 Received ENQ          | (request files)         | S18 |
  238.   |     |          | 3 Received 'C' or NAK   | send EOT                | S14 |
  239.   |     |          | 4 Nothing in 60 seconds | hang up; note can't req | exit|
  240.   |-----+----------+-------------------------+-------------------------+-----|
  241.   | S15 | HonorReqs| 1 Wish to honor requests| Send ENQ                | S16 |
  242.   |     |          | 2 Do not wish to honor  |                         |     |
  243.   |     |          |   requests              | Send CAN                | S18 |
  244.   |-----+----------+-------------------------+-------------------------+-----|
  245.   | S16 | WaitChar | 1 Got ACK               | Get data block, starting|     |
  246.   |     |          |                         | with 2nd byte (ACK is   |     |
  247.   |     |          |                         | the header), check name,|     |
  248.   |     |          |                         | date, password          | S17 |
  249.   |     |          | 2 Got ETB               |                         | S18 |
  250.   |     |          | 3 Nothing in 60 seconds | Hang up; report error   | exit|
  251.   |-----+----------+-------------------------+-------------------------+-----|
  252.   | S17 | SendFile | 1 File exists; date and |                         |     |
  253.   |     |          |   password ok           | Send file using Telink  | S15 |
  254.   |     |          | 2 Can't send file       | Wait for 'C' or NAK from|     |
  255.   |     |          |                         | Telink, send EOT        | S15 |
  256.   |-----+----------+-------------------------+-------------------------+-----|
  257.   | S18 | Request  | 1 Wish to request       |                         | S19 |
  258.   |     |          | 2 Do not wish to request| hang up                 | exit|
  259.   |-----+----------+-------------------------+-------------------------+-----|
  260.   | S19 | WaitChar | 1 Received ENQ          |                         | S20 |
  261.   |     |          | 2 Received CAN          | Hang up; report other   |     |
  262.   |     |          |                         | end refuses requests    | exit|
  263.   |     |          | 3 Nothing in 60 seconds | Hang up                 | exit|
  264.   |-----+----------+-------------------------+-------------------------+-----|
  265.   | S20 | StartReq | 1 No more files to req  | Send ETB; hang up       | exit|
  266.   |     |          | 2 Another file to req   |                         | S21 |
  267.   |-----+----------+-------------------------+-------------------------+-----|
  268.   | S21 | SendBlock|                         | Send data block for this|     |
  269.   |     |          |                         | file, byte by byte      | S22 |
  270.   |-----+----------+-------------------------+-------------------------+-----|
  271.   | S22 | WaitChar | 1 Received ACK          | Receive file with Telink| S20 |
  272.   |     |          | 2 Received other char;  |                         |     |
  273.   |     |          |   10th try              | Hang up; report errors  | exit|
  274.   |     |          | 3 Received other char   | Increment retry count   | S21 |
  275.   |     |          | 4 Nothing in 60 seconds | Hang up; report errors  | exit|
  276.   `-----+----------+-------------------------+-------------------------+-----'
  277.   
  278.  
  279.  
  280. 2.3.3  Answerer Diagram
  281.  
  282.   
  283.   Answerer of Mail Session
  284.   
  285.   .-----+----------+-------------------------+-------------------------+-----.
  286.   |State| State    | Predicate(s)            | Action(s)               | Next|
  287.   |  #  | Name     |                         |                         | St  |
  288.   |-----+----------+-------------------------+-------------------------+-----|
  289.   | R0  | WaitCxD  | 1 carrier detected      |                         | R1  |
  290.   |     |          | 2 external timer expires| report no calls         | exit|
  291.   |-----+----------+-------------------------+-------------------------+-----|
  292.   | R1  | WaitBaud | 1 baud rate detected    | send signon with <cr>s  | R2  |
  293.   |     |          | 2 no detect in ?? secs  | hang up, report no baud | exit|
  294.   |-----+----------+-------------------------+-------------------------+-----|
  295.   | R2  | WaitTsync| 1 TSYNCH received       | (receive mail)          | R3  |
  296.   |     |          | 2 60 seconds timeout    | hang up, report not Fido| exit|
  297.   |-----+----------+-------------------------+-------------------------+-----|
  298.   | R3* | RecMail  |                         | (XMODEM rec packet XR0) | R4  |
  299.   |-----+----------+-------------------------+-------------------------+-----|
  300.   | R4  | XRecEnd  | 1 XMODEM successful     | delay 1 second          | R5  |
  301.   |     |          |                         |   flush input           |     |
  302.   |     |          | 2 XMODEM failed         | hang up, rept mail fail | exit|
  303.   |-----+----------+-------------------------+-------------------------+-----|
  304.   | R5* | RecFiles |                         | (BATCH rec files BR0)   | R6  |
  305.   |-----+----------+-------------------------+-------------------------+-----|
  306.   | R6  | ChkFiles | 1 BATCH recv successful | delay 2 secs            | R7  |
  307.   |     |          | 2 BATCH recv failed     | hang up, report bad file| exit|
  308.   |-----+----------+-------------------------+-------------------------+-----|
  309.   | R7  | AllowPkup| 1 have pickup for sender| receiver becomes sender | R8  |
  310.   |     |          | 2 nothing to pickup     | rept recv ok            | R13 |
  311.   |-----+----------+-------------------------+-------------------------+-----|
  312.   | R8  | WaitClear| 1 no input for 0.5 secs | send TSYNCH = AEH       | R9  |
  313.   |     |          | 2 over 60 seconds       | hang up, report garbage | exit|
  314.   |     |          |   and line not clear    |                         |     |
  315.   |-----+----------+-------------------------+-------------------------+-----|
  316.   | R9  | SendMail |                         | (XMODEM send packet XS0)| R10 |
  317.   |-----+----------+-------------------------+-------------------------+-----|
  318.   | R10 | CheckMail| 1 XMODEM successful     | (Fido registers success)| R11 |
  319.   |     |          | 2 XMODEM fail or timeout| hang up, report mail bad| exit|
  320.   |-----+----------+-------------------------+-------------------------+-----|
  321.   | R11 | SendFiles|                         | (BATCH send files BS0)  | R12 |
  322.   |-----+----------+-------------------------+-------------------------+-----|
  323.   | R12 | CheckFile| 1 BATCH send successful |                         | R13 |
  324.   |     |          | 2 BATCH send failed     | hang up, rept files fail| exit|
  325.   |-----+----------+-------------------------+-------------------------+-----|
  326.   | R13 | Requests | 1 Wish to request files | Send SYN                | R14 |
  327.   |     |          | 2 Do not wish to request|                         | R18 |
  328.   |-----+----------+-------------------------+-------------------------+-----|
  329.   | R14 | WaitChar | 1 Received ENQ          |                         | R15 |
  330.   |     |          | 2 Received CAN          | report other end refuses|     |
  331.   |     |          |                         | requests                | R18 |
  332.   |     |          | 3 Nothing in 60 seconds | hang up; report errors  | exit|
  333.   |-----+----------+-------------------------+-------------------------+-----|
  334.   | R15 | StartReq | 1 No more files to req  | Send ETB                | R18 |
  335.   |     |          | 2 Another file to req   |                         | R16 |
  336.   |-----+----------+-------------------------+-------------------------+-----|
  337.   | R16 | SendBlock|                         | Send data block for this|     |
  338.   |     |          |                         | file, byte by byte      | R17 |
  339.   |-----+----------+-------------------------+-------------------------+-----|
  340.   | R17 | WaitChar | 1 Received ACK          | Receive file with Telink| R15 |
  341.   |     |          | 2 Received other char;  |                         |     |
  342.   |     |          |   10th try              | Hang up; report errors  | exit|
  343.   |     |          | 3 Received other char   | Increment retry count   | R16 |
  344.   |     |          | 4 Nothing in 60 seconds | Hang up; report errors  | exit|
  345.   |-----+----------+-------------------------+-------------------------+-----|
  346.   | R18 | HonorReq | 1 Wish to honor requests| Send ENQ                | R19 |
  347.   |     |          | 2 Do not wish to honor  |                         |     |
  348.   |     |          |   requests              | Send CAN; hang up       | exit|
  349.   |-----+----------+-------------------------+-------------------------+-----|
  350.   | R19 | WaitChar | 1 Got ACK               | Get data block, starting|     |
  351.   |     |          |                         | with 2nd byte (ACK is   |     |
  352.   |     |          |                         | the header), check name,|     |
  353.   |     |          |                         | date, password          | R20 |
  354.   |     |          | 2 Got ETB               | hang up                 | exit|
  355.   |     |          | 3 Nothing in 60 seconds | hang up; report error   | exit|
  356.   |-----+----------+-------------------------+-------------------------+-----|
  357.   | R20 | SendFile | 1 File exists; date and |                         |     |
  358.   |     |          |   password ok           | Send file using Telink  | R18 |
  359.   |     |          | 2 Can't send file       | Wait for 'C' or NAK from|     |
  360.   |     |          |                         | Telink, send EOT        | R18 |
  361.   `-----+----------+-------------------------+-------------------------+-----'
  362.