home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 2 BBS / 02-BBS.zip / FSC.ZIP / FSC-0014.TXT < prev    next >
Text File  |  1988-01-06  |  17KB  |  420 lines
  1. FSC-0014
  2.                                 A Bundle Proposal
  3.  
  4.                                  Wynn Wagner III
  5.                                   January, 1988
  6.  
  7.  
  8. UPFRONT
  9. -------
  10.  
  11. What follows is a proposal for a new structure of message bundles that
  12. are transmitted between Fidonet systems.
  13.  
  14. Currently we deal with "packet version 2."  This is a proposed format
  15. for packet version three.
  16.  
  17. The version number should be recognizable by TYPE-2 programs, but the
  18. older programs will not be able to do anything more than report an
  19. error.  In other words, there is no direct upwards compatibility except
  20. for the offset in the _BundleHeader (see below) of the TYPE-3 signal.
  21.  
  22. Because of this, any conversion should be slow... possibly a year or more.
  23. Interim systems would have to be able to pack and unpack both kinds
  24. of bundles.  It would be required for the packer to know whether its
  25. target system knows about TYPE-3 bundles or not... either by some node
  26. list flag or by using a control file.
  27.  
  28. I think it is important that a new structure be seriously considered,
  29. but it is also vital that we approach such a change with a mind to
  30. keeping it an evolutionary process rather than an overnight revolution.
  31. It is important that TYPE-2 systems be retired using attrition instead
  32. of compulsion.
  33.  
  34. This proposal is described in detail... possibly too much detail.
  35. The design looks scarier than it really is.  Code to process this
  36. kind of a bundle is almost trivial.
  37.  
  38. One design feature is that putting a message bundle together is 
  39. somewhat more involved than taking one apart.  The theory is that we
  40. will be getting more and more tiny installations operating as points.
  41. Collecting and unpacking such things as echomail will be easier even
  42. on small/slow computers.  Heavy volume traffic with lots of packing
  43. and unpacking is usually carried on by computers more capable of
  44. heavy work.  Please note that the added work on the shoulders of
  45. the packer is almost microscopic, but it exists.  This uneven distribution
  46. of the work is intentional.
  47.  
  48.  
  49. ------------------------------------------------------------------------------
  50.  
  51. PRELIMARIES: METHODS
  52. --------------------
  53.  
  54.          Messages are transmitted in "bundles."
  55.  
  56.          A bundle is a sequence of "packets."  Every bundle has at
  57.          least two packets: a header and a footer.
  58.  
  59.          This document describes the layout and use of those
  60.          packets as well as the general format of a bundle.
  61.  
  62.  
  63.    
  64.    
  65. ------------------------------------------------------------------------------
  66.  
  67. PRELIMINARIES: DATA
  68. -------------------
  69.  
  70.  
  71.   #define BUNDLEVER 3
  72.   #define EIDSIZ    (sizeof(struct _Address)+sizeof(unsigned long))
  73.  
  74.   struct _Address {
  75.      unsigned int      Zone;
  76.      unsigned int      Net;
  77.      unsigned int      Node;
  78.      unsigned int      Point;
  79.   };
  80.  
  81.       DATA NOTES:
  82.  
  83.          "WORD" is a two byte unsigned integer with the most significant
  84.                 byte first.  This storage arrangement is backwards from
  85.                 the way INTEL chips store numbers, but it is more in-line
  86.                 with the way the rest of the universe does it.  The
  87.                 conversion for MsDOS and other INTEL programmers is quite
  88.                 trivial.
  89.  
  90.                 A routine called SWAP can be used, where...
  91.  
  92.                         unsigned int pascal SWAP(unsigned int VALUE);
  93.  
  94.                 Here's the code...
  95.  
  96.                             SWAP Proc Near
  97.                                  mov   bx, sp
  98.                                  mov   ax, [bx+2]
  99.                                  xchg  ah, al
  100.                                  ret 2
  101.                             SWAP EndP
  102.  
  103.          "UNSIGNED LONG" is a four byte unsigned integer with the most
  104.                significant word first.  Again, this storage arrangement
  105.                conflicts with the method used by INTEL, but the trans-
  106.                formation to "MSW first" is quite simple and it really
  107.                makes the non-MsDOS programmers feel more comfortable.
  108.  
  109.          "UNSIGNED CHAR" is an 8-bit datum that can have any value
  110.                between 0 and 0xff.
  111.  
  112.          CHARACTER ARRAYS are null-padded unless otherwise noted. There
  113.                is a difference between "null-terminated" (common to
  114.                C-language programming) and "null-padded" found here.
  115.                Unless there is a conflicting note, insignificant bytes
  116.                of a character array must be set to zero.
  117.  
  118.          UNUSED DATA are always set to zero.
  119.  
  120.       
  121.  
  122. ------------------------------------------------------------------------------
  123.  
  124. BUNDLE HEADER
  125. -------------
  126.    
  127.   struct _BundleHeader {
  128.      struct _Address   B_Destination;    /* Address of target system    */
  129.      struct _Address   B_Origination;    /* Address where bndl started  */
  130.      unsigned int      B_Local1;         /* Used by bundler, etc        */
  131.      unsigned int      B_Version;        /* Always 3                    */
  132.      unsigned long     B_CreationTime;   /* Unix-type stamp (1970-base) */
  133.      unsigned int      B_BundlerMajor;   /* Major version of bundler    */
  134.      unsigned int      B_BundlerMinor;   /* Minor version of bundler    */
  135.      unsigned char     B_Password[9];    /* NULL-padded array           */
  136.      unsigned char     B_Local2;         /* Local use only              */
  137.      unsigned char     B_Product[4];     /* Meaningful to same product  */
  138.      unsigned char     B_FTSC[4];        /* Reserved by FTSC            */
  139.   };
  140.  
  141.       BUNDLE HEADER NOTES:
  142.  
  143.          The offset of B_Version coincides with the location of the
  144.          `ver' field in type two bundle headers.
  145.  
  146.          The B_Local1 and B_Local2 fields have no meaning during the
  147.          actual transfer.  It is to hold such information as COST
  148.          and/or BAUD rate of use to the sending system.
  149.  
  150.          B_Password is a NULL-padded field that can contain uppercase
  151.          alpha bytes or ASCII digits.  It should not contain lowercase
  152.          characters, punctuation, control characters, etc.  This is a
  153.          NULL-padded field... not just NULL-terminated.  A maximum of
  154.          8 bytes are significant.
  155.  
  156.          Note that the BUNDLER is identified by product code.  This 
  157.          does NOT necessarily have anything to do with the software
  158.          that actually transmits the bundle.  This structure deals
  159.          with message bundles, and the product identification shows
  160.          which computer program was responsible for that layer of
  161.          a netmail session.  The software providing transportation
  162.          is more properly identified during a session-level negotiation 
  163.          (eg WaZOO's YooHoo) or in a dynamically generated structure 
  164.          (eg TeLink's block zero).  TYPE-3 tries to keep the various
  165.          layers of the system separate and easily identifiable.  This
  166.          document describes data, not the method by which they are
  167.          passed from one system to another.
  168.  
  169.  
  170.       BUNDLE BODY NOTES:
  171.  
  172.          The bundle header packet is followed by one or more of the
  173.          following packet types.  Each of these packets begin with 
  174.          two bytes that identify the packet version and the packet
  175.          type.  In all cases, the version is three (0x03).
  176.  
  177.          Packet types include
  178.  
  179.                   END_SIGNAL        0
  180.                   AREA_HEADER       1
  181.                   MESSAGE_HEADER    2
  182.                   TEXT              3
  183.                   ECHOMAIL_INFO     4
  184.                   MISCINFO          128-256
  185.  
  186.          One message is built using at least two packets (MESSAGE_HEADER
  187.          and TEXT).  Optionally, a message might also have ECHOMAIL_INFO
  188.          and MISCINFO packets.  Packets associated with a message must
  189.          be bundled in numerical order (by packet type)... the header
  190.          comes first, followed by the text, possibly followed by echomail
  191.          information, and possibly ending with some miscellaneous packets.
  192.  
  193.          This arrangement of bundles allows the development of
  194.          state machine type programs which effect efficient message
  195.          processing even on slow or small computers.  Here's a
  196.          quick coding example:
  197.  
  198.                for(;;)
  199.                  switch(fgetc(BUNDLE)) {
  200.                     default:  printf("Not Type-3 message"); return -1;
  201.                     case 3:   switch(fgetc(BUNDLE)) {
  202.                                  case -1: printf("EOF?");   return -1;
  203.                                  case 0:  printf("Done\n"); return 0;
  204.                                  case 1:  GetMsgArea();     break;
  205.                                  case 2:  GetMessage();     break;
  206.                                  default: printf("Pkt?");   break;
  207.                               };
  208.                  };
  209.  
  210.                      NOTE: For those re-reading and spotting what looks
  211.                            like a mistake... the `GetMessage()' routine
  212.                            would also take care of TEXT and any ECHOMAIL  
  213.                            or MISCINFO packets.
  214.  
  215.                            Also, for a little added robustness, the
  216.                            default item that prints "Pkt?" should look
  217.                            for a value of 0x03 (or and end of the file)
  218.                            before returning to the processing loop.
  219.  
  220.  
  221.  
  222. ------------------------------------------------------------------------------
  223.  
  224. BUNDLE FOOTER
  225. -------------
  226.  
  227.   struct _BundleEnd {
  228.      unsigned char     M_Version;        /* Always 3                    */
  229.      unsigned char     M_PacketType;     /* Always 0                    */
  230.   };
  231.  
  232.       
  233.       BUNDLE END NOTES:
  234.  
  235.          All bundles end with this packet.  It is not optional.
  236.  
  237.  
  238.  
  239. ------------------------------------------------------------------------------
  240.  
  241. MESSAGE AREA
  242. ------------
  243.  
  244.   struct _AreaHeader {
  245.      unsigned char     E_Version;        /* Always 3                    */
  246.      unsigned char     E_PacketType;     /* Always 1                    */
  247.      unsigned byte     E_NameLength;     /* Actual bytes in E_Name      */
  248.      unsigned byte     E_Name[1];        /* VARIABLE-length field       */
  249.   };
  250.  
  251.       AREA HEADER NOTES:
  252.  
  253.          The area header packet marks the start of a sequence of
  254.          messages destined for the same message area.
  255.  
  256.          Often E_Name will contain the name of an echomail area.
  257.          If the legnth and first byte of E_Name are zero, it means
  258.          that the following messages are inter-system traffic
  259.          (ie regular netmail).
  260.  
  261.          The maximum value for E_NameLength is 63.
  262.  
  263.          E_Name can contain uppercase characters, digits, and the
  264.          following punctuation: $ . - _ & # @ !
  265.  
  266.          Note that E_NameLength combined with E_Name make up what
  267.          is often considered a "Pascal style string."  E_Name is
  268.          NOT a null-terminated array (aka "ASCIIZ").
  269.  
  270.  
  271.  
  272.  
  273.  
  274. ------------------------------------------------------------------------------
  275.  
  276. MESSAGE HEADER
  277. --------------
  278.  
  279.   struct _MessageHeader {
  280.      unsigned char     M_Version;        /* Always 3                    */
  281.      unsigned char     M_PacketType;     /* Always 2                    */
  282.      struct _Address   M_Destination;    /* FINAL Destination           */
  283.      struct _Address   M_Origination;    /* Where message was entered   */
  284.      unsigned long     M_CreationTime;   /* Unix-type stamp (1970-base) */
  285.      unsigned int      M_Attributes;     /* Standard Fidonet bitweights */
  286.      unsigned char     M_FromLength;     /* Number of bytes in FROM     */
  287.      unsigned char     M_ToLength;       /* Number of bytes in TO       */
  288.      unsigned char     M_SubjectLength;  /* Number of bytes in SUBJECT  */
  289.   };
  290.  
  291.  
  292.       MESSAGE HEADER NOTES:
  293.  
  294.          Every message begins with a message header packet.  This
  295.          structure is created by the system where the message
  296.          originated.  If there are any intermediate stops before
  297.          it reaches its destination, it is the responsibility of
  298.          intermediate systems to maintain all of this information
  299.          without any modification.
  300.  
  301.          Following this header come three char-type data: FROM, TO,
  302.          and SUBJECT.  Using the final three fields of the header,
  303.          a program can quickly read and process/store the the message.
  304.  
  305.          None of the character items is null-terminated.  Their
  306.          lengths are determined by values in the message header.
  307.  
  308.  
  309.  
  310.  
  311.  
  312. ------------------------------------------------------------------------------
  313.  
  314. MESSAGE TEXT/BODY
  315. -----------------
  316.  
  317.   struct _Text {
  318.      unsigned char    T_Version;         /* Always 3                    */
  319.      unsigned char    T_PacketType;      /* Always 3                    */
  320.      unsigned int     T_ByteCount;       /* Number of bytes ( <0x1000)  */
  321.      unsigned int     T_Data[1];         /* VARIABLE-length field       */
  322.   };
  323.  
  324.       TEXT NOTES:
  325.  
  326.          The body of a message is contained in one or more _Text packets.
  327.  
  328.          No _Text packet is ever more than 1000H bytes long.  That's
  329.          4096 bytes to the terminally base-10 folks.  Of course there
  330.          can be an infinite number of text packets, but you are
  331.          absolutely positively guaranteed that with the TYPE-3 method,
  332.          you will never need a buffer larger than 1000H.
  333.  
  334.          In addition to ASCII values 20h through 7Eh (inclusive),
  335.          the following control codes are legal for TEXT data.
  336.          Note that <cr> and <softCR> are NOT in this list.
  337.  
  338.             <stx>  02H  ... material from here to next <lf> is
  339.                             a quote from the parent message
  340.             <lf>   0Ah  ... forced <cr/lf>
  341.             <dle>  10h  ... replicate
  342.  
  343.          Other control characters and values 7fH and above are
  344.          symptoms of a damaged message.
  345.  
  346.          REPLICATE is a three byte sequence:  <dle><value><length>.
  347.          For example, if a message contains the bytes 10h, 20h, 09h ...
  348.          it would mean that message display programs should replicate
  349.          the <space> character nine times.  
  350.  
  351.          There is no minimum or maximum line length.  If there is no
  352.          <lf> before the display program needs one, it is the display
  353.          program's responsibility to provide the needed "line wrap."
  354.  
  355.          One "line" can cross from one _Text packet to another.
  356.  
  357.  
  358.  
  359.  
  360.  
  361. ------------------------------------------------------------------------------
  362.  
  363. ECHOMAIL
  364. --------
  365.  
  366.   struct _EchomailInfo {
  367.      unsigned char     EI_Version;       /* Always 3                    */
  368.      unsigned char     EI_PacketType     /* Always 4                    */
  369.      unsigned char     EI_Parent[EIDSIZ];/* "up" message thread         */
  370.      unsigned char     EI_Child[EIDSIZ]; /* "down" message thread       */
  371.      unsigned int      EI_SeenbyCount;   /* Number of SEENBY items      */
  372.      struct _Address   EI_Seenby[1];     /* VARIABLE-length field       */
  373.   };
  374.  
  375.  
  376.       ECHOMAIL INFO NOTES:
  377.  
  378.             The EI_Parent and EI_Child fields contain some kind of
  379.             identification of the parent and child messages.  The size
  380.             of the fields corresponds to the size of an _Address
  381.             structure plus the size of a Unix-type time stamp.
  382.  
  383.  
  384.  
  385. ------------------------------------------------------------------------------
  386.  
  387. A KLUDGE, BY ANY OTHER NAME...
  388. ------------------------------
  389.  
  390.   struct _MiscInfo {
  391.      unsigned char     MI_Version;       /* Always 3                    */
  392.      unsigned char     MI_PacketType;    /* 0x80-0xff, assigned by FTSC */
  393.      unsigned char     MI_ByteCount;     /* Size of miscinfo data       */
  394.      unsigned char     MI_WhoKnows;      /* Miscellaneous stuff         */
  395.   };
  396.  
  397.  
  398.       MISCELLANEOUS INFO NOTES:
  399.  
  400.             This is the catch-all packet type that replaces "The Dreaded
  401.             IFNA Kludge."
  402.  
  403.             If present, they are the last packets associated with a
  404.             message.  _MiscInfo items are bound to a message, and it
  405.             is the responsibility of any packer to maintain any 
  406.             _MiscInfo packets exactly as they arrived on any message
  407.             that will be retransmitted (ie netmail and echomail).
  408.  
  409.             Values above 0xf0 have a special meaning.  They are 
  410.             reserved for the severe case that FTSC needs to make some
  411.             kind of change that isn't backwards compatible.  In most
  412.             cases, unrecognized _MiscInfo packets should be preserved
  413.             but otherwise ignored.  If the packet type is 0xf0 through
  414.             0xff, it should be considered an error condition not to
  415.             understand the packet.
  416.  
  417.  
  418.                                       ###
  419.  
  420.