Text 8071, 455 rader
Skriven 2016-02-27 13:47:06 av mark lewis (1:3634/12.73)
   Kommentar till text 8064 av Stephen Hurd (44.fido-ftscpubl)
Ärende: FSP-1040.001 draft 0
============================
27 Feb 16 12:25, you wrote to FTSC:

 SH> 1. Fidonet Packets
 SH> ------------------

 SH>   In Fidonet terms, a "packet" is a file which contains zero or more
 SH>   separate messages to be transfered together to a system.  The
 SH>   "original" packet format only supported 3D node addressing (zone, net

s/"original" packet/"original" Type 2 packet/

 SH>   and node numbers) so different new types of packets were developed.
 SH>   None of them have previously been ratified as a standard despite
 SH> being
 SH>   in common use on Fidonet.

 SH>   These type 2 "compatible" formats all use a similar fixed-length
 SH>   header and the same packet message format.

s/packet message/packed message/

[trim]

 SH> 2. Original Type 2 Packet
 SH> -------------------------

 SH>   Originally defined in FSC0001, supports 3D addressing only.  This can
 SH>   cause problems when transferring them to/from points, and across
 SH>   domain gateways.

 SH>   This header has eighteen fields specified below:

 SH> ,-------------------------------------------------------------------.
 SH> | Name     | Offset | Bytes | Type  | Description                   |
 SH> +----------+--------+-------+-------+-------------------------------+
 SH> | origNode | 0      | 2     | Int16 | Node number packet is from    |
 SH> | destNode | 2      | 2     | Int16 | Node number packet is to      |
 SH> | year     | 4      | 2     | Int16 | Year packet was created       |
 SH> | month    | 6      | 2     | Int16 | Month  "     "     "          |
 SH> | day      | 8      | 2     | Int16 | Day    "     "     "          |
 SH> | hour     | 10     | 2     | Int16 | Hour   "     "     "          |
 SH> | minute   | 12     | 2     | Int16 | Minute "     "     "          |
 SH> | second   | 14     | 2     | Int16 | Second "     "     "          |
 SH> | baud     | 16     | 2     | Int16 | See Notes                     |
 SH> | Type     | 18     | 2     | Int16 | MUST have a value of 2        |

this one is pktver... having a 2 means that it is one of the type 2 formats...
if there's a 3 then it is a type 3 packet... a 5 would be a type 5 packet...
the idea of the fixed header was so that software could at least read this one
byte and know if they could possibly handle the pkt or not...

 SH> | origNet  | 20     | 2     | Int16 | Network number packet is from |
 SH> | destNet  | 22     | 2     | Int16 | Network number packet is to   |
 SH> | prodCode | 24     | 1     | Int8  | Assigned by the FTSC          |
 SH> | serialNo | 25     | 1     | Int8  | See Notes                     |
 SH> | password | 26     | 8     | Str   | Packet password, NUL padded   |

str is incorrect for this field... it is a nul padded 8 byte array of
characters... str indicates either an ending nul or a leading length byte...

 SH> | origZone | 34     | 2     | Int16 | Zone number packet is from    |
 SH> | destZone | 36     | 2     | Int16 | Zone number packet is to      |
 SH> | fill     | 38     | 20    | Str   | SHOULD be NULs                |

same thing for fill... it is a nul padded 20 byte array of characters...

 SH> `----------+--------+-------+-------+-------------------------------'

[trim]

 SH> 3. Type 2+ Packet
 SH> -----------------

 SH>   Originally specified in FSC-0039, then updated by FSC-0048, this
 SH>   introduced a mechanism to detect packet type support which, due to
 SH>   multiple incompatible "type 3" packet formats, never really caught on.
 SH>   This "Capability Word" feature is not specified in this document.

not mentioned in this document? which document? it is definitely mentioned in
this one we're reviewing right now ;)

 SH>   The Type 2+ packet added point information and zone information
 SH> before
 SH>   FTS-0001 was updated to include zones.  As a result, the zone numbers
 SH>   are in different places in the Type 2 and Type 2+ packet definitions.
 SH>   Type 2+ was extended to include zone information in the same location,
 SH>   so the type 2+ packet has the zone information twice.  Software
 SH>   creating or modifying packets MUST set these two sets of zone fields
 SH>   to the same values.

 SH>   In the following table, fields on lines beginning with an "H" reflect
 SH>   changes from the type two packet above.

 SH> ,-------------------------------------------------------------------.
 SH> | Name     | Offset | Bytes | Type  | Description                   |
 SH> +----------+--------+-------+-------+-------------------------------+
 SH> | origNode | 0      | 2     | Int16 | Node number packet is from    |
 SH> | destNode | 2      | 2     | Int16 | Node number packet is to      |
 SH> | year     | 4      | 2     | Int16 | Year packet was created       |
 SH> | month    | 6      | 2     | Int16 | Month  "     "     "          |
 SH> | day      | 8      | 2     | Int16 | Day    "     "     "          |
 SH> | hour     | 10     | 2     | Int16 | Hour   "     "     "          |
 SH> | minute   | 12     | 2     | Int16 | Minute "     "     "          |
 SH> | second   | 14     | 2     | Int16 | Second "     "     "          |
 SH> | baud     | 16     | 2     | Int16 | See Notes                     |
 SH> | Type     | 18     | 2     | Int16 | MUST have a value of 2        |
 SH> | origNet  | 20     | 2     | Int16 | Network number packet is from |
 SH> | destNet  | 22     | 2     | Int16 | Network number packet is to   |
 SH> | prodCode | 24     | 1     | Int8  | Assigned by the FTSC          |
 SH> |          |        |       |       | (Low byte only)               |
 SH> H prodVerM | 25     | 1     | Int8  | Major Version Number          |
 SH> | password | 26     | 8     | Str   | Packet password, NUL padded   |

str again... should be array...

 SH> | origZone | 34     | 2     | Int16 | Zone number packet is from    |
 SH> | destZone | 36     | 2     | Int16 | Zone number packet is to      |
 SH> H auxNet   | 38     | 2     | Int16 | origNet when orig is a point  |
 SH> H capValid | 40     | 2     | Int16 | See Notes                     |
 SH> H prodCodH | 42     | 1     | Int8  | Assigned by the FTSC          |
 SH> H          |        |       |       | (High byte only)              |
 SH> H prodVerN | 43     | 1     | Int8  | Minor Version Number          |
 SH> H capWord  | 44     | 2     | Int16 | See Notes                     |
 SH> H origZ2   | 46     | 2     | Int16 | See Notes                     |
 SH> H destZ2   | 48     | 2     | Int16 | See Notes                     |
 SH> H origPnt  | 50     | 2     | Int16 | Point number packet is from   |
 SH> H destPnt  | 52     | 2     | Int16 | Point number packet is to     |
 SH> H prodData | 54     | 4     | Int32 | Product-specific data         |
 SH> `----------+--------+-------+-------+-------------------------------'

 SH>   Notes:
 SH>   auxNet
 SH>     If origNet is 65535 (0xffff), indicates that the originator is a
 SH>     point, and the originating network can be found in this field.
 SH>     Some old software may not follow this convention, so the network
 SH>     number may be found in either of the two fields.  When parsing a
 SH>     type 2+ packet, if origNet is 65535, the software MUST use the
 SH>     value from the auxNet field.  When creating a packet, if the
 SH>     originating system is a point, it SHOULD set origNet to 65535 and
 SH>     put the net number in this field.  In the case where the originating
 SH>     net is 65535 (As recommended by Policy 4), it SHOULD be placed in
 SH>     both origNet and auxNet.

where is this recommendation by P4? why are political documents being
referenced in a technical document?

aside from that, it doesn't make sense as to why software should do this when
the original fields are specifically there to hold this data... the /only/
thing in can think of as to why this might be done is for the old fakenet (aka
pointnet) stuff done for points so that they looked like zone:net/node
addresses... i forget the boundary but net numbers above a certain value were
fakenets for points... this was done specifically for point systems before the
pkts could carry the point information so they faked it by pretending to be a
net and their point number was placed in the node field... type 2+ started
allowing points to be represented as actual points without the fakenet mess
being needed...

 SH>   capValid
 SH>     Byte-swapped copy of the least-significant 15 bits of capWord.
 SH>     That is to say that the most significant bit of capWord is masked
 SH>     off, and the resulting two bytes are swapped.  In C:
 SH>     capValid = ((capWord & 0x7f00) >> 8) | ((capWord & 0xff) << 8));

 SH>     If the capValid and capWord fields do not match, the packet SHOULD
 SH>     NOT be processed as a type 2+ packet.

 SH>   prodVerM
 SH>     Major version number of product generating the packet.  This
 SH>     replaces the serialNo field of packet type 2.

 SH>   prodCodH
 SH>     High (most-significant) byte of FTSC-assigned product code.

 SH>   prodVerN
 SH>     Minor version number of product generating the packet.

 SH>   capWord
 SH>     Capability Word.  Not specified in this document, SHOULD have a
 SH>     value of 1.  MUST at least have the least significant bit set (ie:
 SH>     be an odd number) or the packet is not a valid type 2+ packet.

 SH>   origZ2
 SH>     A copy of origZone.  If origZone and origZ2 are different, the
 SH>     non-zero one SHOULD be used.  If neither is zero, origZ2 SHOULD be
 SH>     used.  A compliant program MUST set these two fields to the same
 SH>     value.

 SH>   destZ2
 SH>     A copy of destZone.  As with origZ2, this is the "preferred" copy
 SH>     for software to use.

since these two are the preferred, rename the other two and leave these as
OrigZone and DestZone.. especially to avoid possible confusion with "Z2"
meaning "zone 2"... ya never know what new budding programmers or average joes
may be reading to learn about the intracasies of FTN stuffs... in my code, i
actually have the other two named qorgzone and qdstzone... the 'q' being
significant for some old piece of software but i don't recall which one...

 SH>   origPnt
 SH>     Point number of the originating system.

 SH>   destPnt
 SH>     Point number of the destination system.

 SH>   prodData
 SH>     Value defined by the holder of the FTSC product code specified.


 SH> 4. Type 2.2 Packet
 SH> ------------------

 SH>   Originally specified in FSC-0045, this packet format supports full 5D
 SH>   addressing.

 SH>   The type 2.2 packet format adds both point and domain information, but
 SH>   replaces some rarely used fields, so is not as compatible with type 2
 SH>   as type 2+ is.

 SH>   In the following table, fields on lines beginning with an "H" reflect
 SH>   changes from the type two packet in section 2.

pedantic: s/type two packet/type 2 packet/

probably should also standardize on "Type" being capatilized, too... Type 2,
Type 2+, Type 2.2...

 SH> ,-------------------------------------------------------------------.
 SH> | Name     | Offset | Bytes | Type  | Description                   |
 SH> +----------+--------+-------+-------+-------------------------------+
 SH> | origNode | 0      | 2     | Int16 | Node number packet is from    |
 SH> | destNode | 2      | 2     | Int16 | Node number packet is to      |
 SH> H origPnt  | 4      | 2     | Int16 | Point number packet is from   |
 SH> H destPnt  | 6      | 2     | Int16 | Point number packet is to     |
 SH> H fill     | 8      | 8     | Str   | MUST be NULs                  |
 SH> H subType  | 16     | 2     | Int16 | MUST have a value of 2        |
 SH> | Type     | 18     | 2     | Int16 | MUST have a value of 2        |
 SH> | origNet  | 20     | 2     | Int16 | Network number packet is from |
 SH> | destNet  | 22     | 2     | Int16 | Network number packet is to   |
 SH> | prodCode | 24     | 1     | Int8  | Assigned by the FTSC          |
 SH> H prodRev  | 25     | 1     | Int8  | See Notes                     |
 SH> | password | 26     | 8     | Str   | Packet password, NUL padded   |
 SH> | origZone | 34     | 2     | Int16 | Zone number packet is from    |
 SH> | destZone | 36     | 2     | Int16 | Zone number packet is to      |
 SH> H origDom  | 38     | 8     | Str   | Domain packet is from,        |
 SH> H          |        |       |       | NUL padded                    |
 SH> H destDom  | 46     | 8     | Str   | Domain packet is to,          |
 SH> H          |        |       |       | NUL padded                    |

again with the str... they're nul padded (actually nul filled) arrays of
characters... there's no trailing nul byte and no leading length byte...

 SH> H prodData | 54     | 4     | Int32 | Product-specific data         |
 SH> `----------+--------+-------+-------+-------------------------------'

[trim]

 SH> 5. Packed Message
 SH> -----------------

 SH> All type 2 compatible formats share the same packed message format.
 SH> It consists of a fixed-length header followed by variable-length header
 SH> followed by the message text.

i've never heard it expressed in this manner... specifically the
"variable-length header" part... that section should be better indicate below
as you have done with the fixed-length header here... see below...

 SH> The fixed-length header is as follows:

 SH> ,-------------------------------------------------------------------.
 SH> | Name      | Offset | Bytes | Type  | Description                  |
 SH> +-----------+--------+-------+-------+------------------------------+
 SH> | Type      | 0      | 2     | Int16 | MUST have a value of 2       |
 SH> | origNode  | 2      | 2     | Int16 | Node number packet is from   |
 SH> | destNode  | 4      | 2     | Int16 | Node number packet is to     |
 SH> | origNet   | 6      | 2     | Int16 | Network number packet is from|
 SH> | destNet   | 8      | 2     | Int16 | Network number packet is to  |
 SH> | attribute | 10     | 2     | Int16 | See Notes                    |
 SH> | cost      | 12     | 2     | Int16 | See Notes                    |
     | datetime  | 14     | 20    | array | 19 chars + NUL; see notes    |
 SH> `-----------+--------+-------+-------+------------------------------'

The variable-length header is as follows:

 ,--------------+-------+--------------+---------------------------------.
 | Name         | Type  | # Bytes      | Description                     |
 +--------------+-------+--------------+---------------------------------+
 | toUserName   | array | up to 36+NUL | MUST be NUL terminated          |
 | fromUserName | array | up to 36+NUL | MUST be NUL terminated          |
 | MsgSubject   | array | up to 72+NUL | MUST be NUL terminated          |
 `--------------+-------+--------------+---------------------------------'

"array" in the above may be better known as a "C string" or a "nul terminated
string"... some languages have to take special care to process them correctly
as they don't read/understand them natively...

then follow with something like

the message body is unbounded. that means that it is not limited in size by
this specification. the message body should be composed of paragraphs
terminated by 0x0d. there should not be any line breaks attempting to limit the
length of the lines in a paragraph. display of the paragraph is handled by the
terminal and it should deal with the wrapping of paragraph lines according to
its view port on the client's display.

and then maybe describe the mess that the older software creates... including
that so-called soft-CR that some software used to indicate a line break...

 SH>   Notes:

 SH>   origNode/origNet
 SH>     Net and node the message originated from (not the node the packet
 SH>     was created on).

 SH>   destNode/destNet
 SH>     Net and node the message is directed to (not the node the packet is
 SH>     directed to).

 SH>   attribute
 SH>     The attribute word of the message.  The following bits are defined,
 SH>     any undefined bits MUST be zeroed before the message is packed.
 SH>     When processing these packets, undefined attributes MUST be ignored.

 SH>     ,--------------------------------.
 SH>     | Bit | Meaning                  |
 SH>     +-----+--------------------------|
 SH>     | 0   | Private                  |
 SH>     | 1   | Crash                    |
 SH>     | 4   | File Attached            |
 SH>     | 10  | unused                   |
 SH>     | 12  | Return Receipt Requested |
 SH>     | 13  | Is a Return Receipt      |
 SH>     | 14  | Audit Request            |
 SH>     `-----+--------------------------'

 SH>     Bit 10 SHOULD be retained unchanged when packing messages despite it
 SH>     being unused.  All other bits SHOULD be cleared when packing.  The
 SH>     attributes can be ANDed with 29715 (0x7413) to clear the appropriate
 SH>     bits.

 SH>   cost
 SH>     Expressed in the lowest unit of originators currency.  Usually set
 SH>     to zero.

===== snip =====
 SH>   After the fixed-length portion is a series of NUL terminated
 SH> strings.
 SH>   In order, they are:

 SH>     dateTime (Length = 19)
 SH>     toUserName (Length <= 36)
 SH>     fromUserName (Length <= 36)
 SH>     subject (Length <= 72)
 SH>     text
===== snip =====

cut the about section between the "snips" as it is right below the fixed-length
header chart now...

 SH>   The lengths above do NOT include the NUL terminator.

shouldn't need this line with the above chart...

 SH>   dateTime MUST occupy twenty bytes including the NUL terminator.  The
 SH>   following is the ABNF notation of the format that messages SHOULD use:

definitely keep these notes to go with the charts...

 SH>     digit      = "0" / "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" /
 SH>                  "9"

 SH>     dayOfMonth = "00" / "01" / "02" / "03" / "04" / "05" / "06" / "07" /
 SH>                  "08" / "09" / "10" / "11" / "12" / "13" / "14" / "15" /
 SH>                  "16" / "17" / "18" / "19" / "20" / "21" / "22" / "23" /
 SH>                  "24" / "25" / "26" / "27" / "28" / "29" / "30" / "31" /

 SH>     month      = "Jan" / "Feb" / "Mar" / "Apr" / "May" / "Jun" / "Jul" /
 SH>                  "Aug" / "Sep" / "Oct" / "Nov" / "Dec"

 SH>     year       = 2*( digit )

 SH>     hour       = "00" / "01" / "02" / "03" / "04" / "05" / "06" / "07" /
 SH>                  "08" / "09" / "10" / "11" / "12" / "13" / "14" / "15" /
 SH>                  "16" / "17" / "18" / "19" / "20" / "21" / "22" / "23" /
 SH>                  "24"

 SH>     oneToSixty = "00" / "01" / "02" / "03" / "04" / "05" / "06" / "07" /
 SH>                  "08" / "09" / "10" / "11" / "12" / "13" / "14" / "15" /
 SH>                  "16" / "17" / "18" / "19" / "20" / "21" / "22" / "23" /
 SH>                  "24" / "25" / "26" / "27" / "28" / "29" / "30" / "31" /
 SH>                  "32" / "33" / "34" / "35" / "36" / "37" / "38" / "39" /
 SH>                  "40" / "41" / "42" / "43" / "44" / "45" / "46" / "47" /
 SH>                  "48" / "49" / "50" / "51" / "52" / "53" / "54" / "55" /
 SH>                  "56" / "57" / "58" / "59" / "60"

 SH>     minute     = oneToSixty

 SH>     second     = oneToSixty

there can be 61 seconds on the day when a lead-second is added... not allowing
for that can cause problems with some software depending on what they do with
the time fields...

 SH>     dateTime   = dayOfMonth " " month " " year "  " hour ":" minute
 SH> ":"
 SH>                  second %x00

 SH>     January 1st, 2016 at 11:15:55pm would therefore be
 SH>     "01 Jan 16  23:15:55" with a NUL at the end.  Notice the two spaces
 SH>     between the year and the hour.

 SH>     This format ensures the broadest compatibility however, other
 SH>     formats are known to be in use.  SEAdog has been known to use the
 SH>     format "Mon  1 Jan 86 02:34" with a single NUL terminator.

these are the only two formats that i've ever seen... the seadog format comes
from the C ISO time format stuff, IIRC... it has a non-zero-padded day of month
but the time is zero-padded but only hours and minutes... the other (more
popular) format dropped the day of week and added a colon plus the seconds to
the time portion... that took care of the three characters the day of week
used... it had to leave the extra space that trailed the removed day of week to
maintain the field length so it moved that space and added it between the two
digit year and the hour for two spaces in that position...

 SH>   After the message text is either the next message or the two-NUL
 SH>   packet terminator.

 SH>   Some old systems MAY terminate the message text with an EOF (0x1A)

or they just terminate the file with no EOF character...

 SH>   Some even older systems MAY terminate the message text with an empty
 SH>   line (0x0D 0x0A 0x0D 0x0A).  To detect this, software MAY use the
 SH> NUL
 SH>   in the second byte of the Type field to attempt to resynchronize.  It
 SH>   is up to the developer if this needs to be supported.

between messages there should be at least one NUL... message bodies are
unbounded in length but they SHOULD be NUL terminated by the existing spec...
the tail end of a properly terminated PKT with at least one packed message
contains three NUL characters... one for the packed message body termination
and two for the PKT termination...

[trim]

over all, excellent work gathering this all together and presenting it like
this... i hope you take my comments in the manner they are intended :)

)\/(ark

Always Mount a Scratch Monkey

... I'm so poor I can't even pay attention.
---
 * Origin:  (1:3634/12.73)