home *** CD-ROM | disk | FTP | other *** search
/ Collection of Hack-Phreak Scene Programs / cleanhpvac.zip / cleanhpvac / DEVELOP.ZIP / HEADERS.DOC < prev    next >
Text File  |  1993-04-27  |  21KB  |  413 lines
  1.   WARNING:  This document is subject to change at any time.  Any changes made
  2.   will be indicated by a vertical bar (|) in column 1 of the file.
  3.  
  4. | Last update: 04/27/93
  5.  
  6. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  7.  
  8.   The following is the standard message header (128 byte block) with only
  9.   slight modifications:
  10.  
  11.   typedef struct {
  12.     char    Status;
  13.     bassngl MsgNumber;
  14.     bassngl RefNumber;
  15.     char    NumBlocks;      <- see bit #7 of ExtendedStatus
  16.     char    Date[8];
  17.     char    Time[5];
  18.     char    ToField[25];
  19.     bassngl ReplyDate;
  20.     char    ReplyTime[5];
  21.     char    ReplyStatus;
  22.     char    FromField[25];
  23.     char    SubjField[25];
  24.     char    Password[12];
  25.     char    ActiveFlag;
  26.     char    EchoFlag;
  27.     char    Reserved1[4];    <- reserved was 6 bytes
  28.     char    ExtendedStatus;  <- new byte - 0 for compatibility, accept 32 also
  29.     char    Reserved2;       <- last of original reserved bytes
  30.   } msgheadertype;
  31.  
  32.   The message base format remains almost 100% identical to the PCBoard v14.x
  33.   standard.  In fact, it remains 100% compatible having just one byte
  34.   different, which was not previously used by PCBoard.
  35.  
  36.   The byte at offset 126 (i.e.  the 127th byte of the 128 byte header) has a
  37.   new function.  It is now used to indicate that extended header information
  38.   will be found in the body of the message.
  39.  
  40.   The byte, referenced as ExtendedStatus above, will contain a 0 by default to
  41.   indicate that no extended header information is available.  A value of 32
  42.   will also be accepted to indicate the same thing since some programs may be
  43.   placing a space instead of a null character in the reserved byte(s).
  44.  
  45.   If ExtendedStatus is not equal to 0 or 32 then it is assumed that extended
  46.   header information is available, however, a follow-up check of the message
  47.   body will determine the true existence, or lack thereof, of such information.
  48.  
  49.   For speed purposes, ExtendedStatus will be divided into 'bits' as follows:
  50.  
  51.     bit 0 = extended header has TO information
  52.     bit 1 = extended header has FROM information
  53.     bit 2 = extended header has SUBJECT information
  54.     bit 3 = extended header has CARBON LIST TO information
  55.     bit 4 = extended header has ATTACHED FILE information
  56.     bit 5 = ignore - this bit is equal to decimal 32
  57.     bit 6 = extended header has either REQRR or ACKRR information
  58.     bit 7 = reserved for future use
  59.  
  60.   Bit 6 indicates that either an REQRR (request return receipt) or an ACKRR
  61.   (acknowledge return receipt) extended header is in the message.
  62.  
  63.   The following structure will be used within the contents of a message body
  64.   whenever an extended header is to be included:
  65.  
  66.   typedef struct {
  67.     int   Ident;        16639 (40FF hex)
  68. |   char  Function[7];  TO,TO2,FROM,FROM2,SUBJECT,ATTACH,LIST,ROUTE,ORIGIN,REQRR,ACKRR,ACKNAME,PACKOUT
  69.     char  Colon;        always set to ":"
  70.     char  Descript[60]; user name, subject, filename
  71.     char  Status;       NONE, READ (if LIST)
  72.     char  CarReturn;    0xE3 or 0x0D
  73.   } msgextendtype;
  74.  
  75.   There can be as many extended headers as desired.  In fact, no headers at all
  76.   is possible even though the ExtendedStatus from the message header told
  77.   PCBoard to expect to find one.  This, of course, has a negative impact on
  78.   efficiency (don't set the flag unless you really intend to put an extended
  79.   header in the body of the message) but maintains complete compatibility with
  80.   previous versions of PCBoard which totally ignored the values found where the
  81.   ExtendedStatus byte is now located.
  82.  
  83.   The first field, Ident, serves to indicate that a truly valid header is about
  84.   to follow.  Ident is an integer value of 40FFh.  Stored in the file it is
  85.   seen as an ascii 255 character followed by an @ character.
  86.  
  87.   Older software will not expect this extended header to be in there and will
  88.   display the header to the user.  The format of the information, however, is
  89.   such that it will be meaningful, albeit, somewhat annoying to see.
  90.  
  91. | The function of the header is written in english.  Right now the following
  92. | are valid values for PCBoard:  "TO     ", "TO2    ", "FROM ", "FROM2  ",
  93. | "SUBJECT", "ATTACH ", "LIST ", "ROUTE ", "ORIGIN ", "REQRR  ", "ACKRR  ",
  94. | "ACKNAME" and "PACKOUT".  Any other values are permissable but will be
  95. | ignored by PCBoard v15.0 unless and until future updates to PCBoard add
  96. | new-standards.
  97.  
  98.   The next character in the header is a colon which is then followed by the
  99.   appropriate text for the header.  For example, the header might be structured
  100.   like this:
  101.  
  102.      <255><@>SUBJECT:any subject you wish to put here, up to 60 characters
  103.  
  104.   Notice how an older program, which is not PCB v15.0-aware, will still display
  105.   something intelligible to the user who is reading the message.  Because the
  106.   entire text is in english the user will be faced with extra information that
  107.   is not utilized by the software he is using, but at the same time, the extra
  108.   information does not make his software incompatible or unusable.  This
  109.   protects the user's investment in software and time, especially if the author
  110.   is no longer supporting the program, or the user does not have time to switch
  111.   programs or upgrade to a newer package which may have more bells and whistles
  112.   than he cares to learn.
  113.  
  114.   Of course, older packages will not be able to take advantage of the added
  115.   functionality since the header information will be very difficult to enter
  116.   properly via the keyboard.  So, while remaining compatible with older
  117.   software, to take advantage of the new features a user will still have to
  118.   upgrade to a newer release of the package.
  119.  
  120.   The text for the header may be up to 60 bytes long.  If the Function is set
  121.   to "TO" then the header indicates a longer, or alternate, name should be used
  122.   when displaying the TO:  field of the message.  If the Function is set to
  123.   "LIST" then the header indicates the name of ONE of the users who is to
  124.   receive the message.  There may be more than one "LIST" header, in fact, it
  125.   is expected that any time you create a carbon copy list you will be sending
  126.   the message to two or more users.  If the Function is set to "FROM" then it
  127.   indicates a longer, or alternate, name should be displayed for the FROM:
  128.   field.  If set to "SUBJECT" then a longer, or alternate, subject is
  129.   displayed.  If set to "ATTACH" then the description field indicates the name
  130.   of the attached file.  If set to ROUTE then message routing information (for
  131.   netmail transfers) will be included.  If set to ORIGIN then the origin of the
  132.   message (for netmail transfers) will be included.  If set to REQRR then
  133.   PCBoard will generate a Return Receipt when the user reads the message
  134.   online.  Mail Doors will need to be enhanced to perform the same
  135.   functionaility.  If set to ACKRR this will indicate that an acknowledgement
  136.   to the Return Receipt is contained in the message.  One additional header,
  137.   the ACKNAME, will be included with ACKRR to complete the acknowledgement.
  138.  
  139.   The next byte is the extended header status byte.  To help guarantee that the
  140.   header is valid, there are only three possible values for this field.  They
  141.   are:  'N', and 'R'.  These values are used as follows:
  142.  
  143.      'N' indicates that there is no status - it is used just for verification
  144.      'R' indicates that a user in a CARBON COPY LIST has read the message
  145.  
  146.   The 'R' allows PCBPack to determine when all intended recepients have read
  147.   the message.  Each user is listed in a separate header and each user
  148.   therefore has a separate status byte to indicate when it has been read.  Once
  149.   all users have read the message it may then be deleted.
  150.  
  151.   Finally, the CarReturn byte is set to E3 hex.  This is the same character
  152.   that is normally used by PCBoard to indicate the end of a line.  By
  153.   terminating the header in this manner all non-v15.0-aware packages will be
  154.   able to properly display the entire header in a legible form.  The 0D hex
  155.   value is used by foreign systems (such as the Chinese version of PCBoard) in
  156.   place of E3.  This is because E3 interferes with the double-byte character
  157.   system used by these countries.
  158.  
  159.   Remember too, that other systems/software could pass other values through
  160.   the extended header field.  PCBoard v15.0 will ignore (and not display)
  161.   any extended headers it does not understand.  Thus, if an offline reader were
  162.   to pass additional information into the message base it would be posted and
  163.   downloaded through any of the existing mail doors.  The downloader then,
  164.   having access to an updated reader, could take advantage of the additional
  165.   information that was passed to it.  For instance, a header of "GIF" might be
  166.   passed as well as a filename.  If the door were updated to know that it
  167.   should send the attached file too then the offline reader could use the
  168.   extended header "GIF" to know that it can display the file to the caller.
  169.   Possibilities are limitless.
  170.  
  171.  -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  172.  he following outlines implementation details of the new system, covering
  173.  ach of the headers supported by PCBoard v15.0:
  174.  -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  175.  
  176.   FROM
  177.   ----
  178.   For v15.0, this field allows a name that is longer than 25 characters to be
  179. | stored in the message.  In order to ENTER a name that is longer than 25
  180. | characters, however, the conference must have the "Allow Internet TO: Names"
  181. | switch enabled.  Of course, the only way to edit the FROM field is to use
  182. | the (E)dit Header command.
  183.  
  184.   If the message header FROM field is blank (all spaces) then PCBoard will
  185.   display only the extended header FROM field.
  186.  
  187.   If the message header FROM field is not blank, then PCBoard will display
  188.   the extended header FROM field, then a comma, then the message header FROM
  189.   field.
  190.  
  191. | FROM2
  192. | -----
  193. | This field is only expected to exist if the FROM field is utilized first.
  194. | It allows another 60 characters to be used for the FROM field.  PCBoard will
  195. | automatically piece together the two FROM/FROM2 fields and will perform any
  196. | wrapping on screen as necessary.
  197.  
  198.   TO
  199.   --
  200.   For v15.0, this field allows a name that is longer than 25 characters to be
  201.   stored in the message.  PCBoard only allows a caller to type in a TO name
  202.   longer than 25 characters if Internet style (long) addresses are enabled
  203.   via PCBSetup.  This is done on a per-conference basis.
  204.  
  205.   If the message header TO field is blank (all spaces) then PCBoard will
  206.   display only the extended header TO field.
  207.  
  208.   If the message header TO field is not blank, then PCBoard will display first
  209.   the extended header TO field, then a comma, then the message header TO field.
  210.  
  211. | TO2
  212. | ---
  213. | This field is only expected to exist if the TO field is utilized first.
  214. | It allows another 60 characters to be used for the TO field.  PCBoard will
  215. | automatically piece together the two TO/TO2 fields and will perform any
  216. | wrapping on screen as necessary.
  217.  
  218.   SUBJECT
  219.   -------
  220.   If an alternate subject is supplied it will be displayed in the message
  221.   header instead of the 25-character subject found in the main header.  If the
  222.   caller replies to the message the alternate subject is automatically carried
  223.   forward.
  224.  
  225.   ATTACH
  226.   ------
  227.   When saving the message the caller may attach a file by uploading it while
  228.   in the editor.  PCBoard will use standard file transfer protocols to receive
  229.   the file.  The filename will be stored in the header.  NO PATH information
  230.   will be included.  PCBoard must be configured with each conference set to
  231.   a separate file attachment subdirectory.  By not including the path
  232.   information in the header, the files may be moved simply by changing the
  233.   PCBoard configuration.  If a user reads the message through PCBoard he will
  234.   be prompted to download the attached file.  If the user downloads the message
  235.   through an offline mail reader then it is up to the mail door author to
  236.   provide options for 'always' downloading the file, 'never' downloading the
  237.   file, or provide the ability to call back later to pick the file up.
  238.  
  239.   The "Descript" field of the extended header will be formatted as follows:
  240.  
  241.      FILENAME.EXT (FILESIZE) UNIQUE.###
  242.  
  243.   The first filename is the actual name of the file that is being attached.
  244.  
  245.   The file size is the proper size of the file.
  246.  
  247.   The unique filename is the name which is used to STORE the file on disk.
  248.   Because of the possibility of more than one message having the same name
  249.   for a file attachment, it is necessary to use a unique storage name.
  250.   PCBoard will display only the first filename and size to the caller.  But
  251.   when the caller downloads the file, PCBoard will have to copy the stored
  252.   name to the proper filename first, then perform the file transfer.
  253.  
  254.   PCBoard has implemented the unique filename by simply taking the original
  255.   filename and changing the extension to ".000" for the first file by that
  256.   name, ".001" for the second, ".002" for the third and so on.  In other
  257.   words, when a caller uploads an attached file, PCBoard will check for any
  258.   previously existing "FILENAME.000" file.  If one is found, then it will
  259.   check for a "FILENAME.001" file and so on until a unique name can be
  260.   posted.
  261.  
  262.   For offline mail doors, the door software will have to perform the same
  263.   operation as PCBoard - ensuring that the file is posted in the proper
  264.   directory and that it has a unique name.  The extended header MAY need
  265.   to be updated before posting the message in the message base!
  266.  
  267.   LIST
  268.   ----
  269.   When writing a message it can sometimes be advantageous to send a single
  270.   message to two or more individuals without:  1) making the message public,
  271.   or 2) making separate copies of the message for each recipient.  When
  272.   addressing the message the caller may indicate, by typing 'LIST' in the TO:
  273.   field, that he or she desires that PCBoard prompt for a list of names to
  274.   store in the extended header.  Each name entered is acted upon similar to
  275.   the TO field described above.  Each name is stored in its own unique header
  276.   with an initial Status byte of 'N'.  The message will be viewable only to
  277.   those in the list and the sysop.  As each intended recipient reads the
  278.   message the Status byte for the appropriate extended header will be changed
  279.   to an 'R'.  WARNING:  Older mail doors will not know to set this byte.  The
  280.   message could, in fact, be read by all users in the list, but not be flagged
  281.   as having be read by all, unless the mail door(s) in use are properly updated
  282.   to perform this function.  This merely means that PCBPack will not know to
  283.   delete the message by seeing if the message has been read.  Instead, it will
  284.   have to remove the message based on age or message number limits as set by
  285.   the sysop.
  286.  
  287.   ROUTE
  288.   -----
  289.   PCBoard can prompt a caller for routing information if the sysop has
  290.   configured it to do so.  A NETMAIL system that receives the message should
  291.   verify that it was intended for the BBS that received it.   If the caller is
  292.   replying to a message then ROUTE automatically receives the contents of the
  293.   ORIGIN field, if one exists, and the caller is not prompted to enter the
  294.   routing information.
  295.  
  296.   ORIGIN
  297.   ------
  298.   This field is filled in by PCBoard using a default specified in the PCBoard
  299.   configuration IF the sysop has configured it to do so.  If an ORIGIN field is
  300.   found, the NETMAIL software that is exporting the message may accept the
  301.   default or it may modify it in a manner that is compatible with the NETMAIL
  302.   package in case it is different from that used by PCBoard.
  303.  
  304.   The default ORIGIN field will be straight text which simply identifies the
  305.   BBS system.  This is similar to the method used by PCRELAY software which
  306.   uses a 7 (or is it 8?) character name to indicate the origin.  The length
  307.   allowed by PCBoard for the ORIGIN line is the full 60 character limit of
  308.   the extended header.
  309.  
  310.   To reiterate:  This scheme need not be used by the NETMAIL software.  The
  311.   ORIGIN field may be replaced with one that is compatible with the NETMAIL
  312.   software being used to echo a particular conference.  HOWEVER, where multiple
  313.   netmail systems share a single conference it is highly desireable that the
  314.   NETMAIL software be written to keep the origin intact and use some type of
  315.   look-up table to determine any other necessary information.
  316.  
  317.   REQRR
  318.   -----
  319.   This packet indicates that the caller is requesting that a return receipt
  320.   message be generated as soon as the message is received by the addressee.
  321.  
  322.   If the caller reads the message online (via PCBoard) then PCBoard will
  323.   immediately generate a return message addressed to the TO field.  It will
  324.   also use the extended header TO, SUBJECT, and ORIGIN information to get the
  325.   message back to the originator.  The message generated will include an
  326.   ACKRR to indicate that it is an acknowledgement.  No other information will
  327.   be in the body of the message.
  328.  
  329.   The "Descript" field of the extended header, when generated by PCBoard,
  330.   will say "Caller has requested a Return Receipt".  This will allow those
  331.   using incompatible software to at least understand what is happening.
  332.  
  333.   PCBoard, when displaying the message to the caller, will indicate at the
  334.   bottom of the message that the sender has requested a Return Receipt.  If
  335.   this is the first time the message has been read then it will also indicate
  336.   that the Return Receipt is being generated right then.
  337.  
  338.   ACKRR
  339.   -----
  340.   When a caller views an ACKRR message online (via PCBoard), PCBoard will use
  341.   the current language (pcbtext file) to display the acknowledgement to the
  342.   caller appropriately.  No other information in the body of the message will
  343.   be shown to the caller.
  344.  
  345.   The "Descript" field of the extended header will be formatted as follows:
  346.  
  347.      "Acknowledge Receipt of msg ###### written on ##/##/## ##:##"
  348.  
  349.   PCBoard will read the Descript field and parse out the written on
  350.   ##/##/## ##:## information.  If the reply message number is 0 then it
  351.   will also use the "msg #####" portion.  Then, using the pcbtext file,
  352.   it will display an appropriate message to the caller to indicate that
  353.   the message he or she wrote on MM/DD/YY at HH:MM has been received.
  354.  
  355.   The FROM field of the message header will say "RETURN RECEIPT".  An
  356.   ACKNAME header will will be included in to indicate the actual name of
  357.   the caller having received the message.
  358.  
  359.   ACKNAME
  360.   -------
  361.   This field is used in conjuction with ACKRR to indicate the name of the
  362.   user that received the message.
  363.  
  364.   PACKOUT
  365.   -------
  366.   This field holds a date in the form MM/DD/YY which specifies the date for
  367.   when a message should be packed out.  As long as the message has not been
  368.   killed, the message will remain in the message base until that date.
  369.  
  370.  -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  371.  uestion and Answer Section
  372.  -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  373.  
  374.   Q: With the long name and subject fields possible, what is going to happen
  375.   to the header display in PCBoard when reading messages?
  376.  
  377.   A: The following is the proposed header display format:
  378.  
  379.   Date: 10-01-92 (01:01)            Number: 1100 of 1200 (Refer 1050)
  380.     To: A very long name can be used here, ACCOUNT NAME
  381.   From: From another long named user, ACCOUNT NAME
  382.   Subj: A very long subject - mixed case is possible throughout
  383.   Read: 08-15-92 (17:10)            Status: PUBLIC MESSAGE / FILE / LIST
  384.   Conf: MAIN BOARD (0)           Read Type: GENERAL (+)
  385.  
  386.   The above example shows what a header might look like if the TO, FROM and
  387.   SUBJECT fields were all replaced with extended header information.  It also
  388.   shows what the header would look like if a file were attached and the message
  389.   were addressed to a list of users (carbon copy list).
  390.  
  391.   Q: Where will attached files be stored?
  392.  
  393.   A: Each conference can be configured with a unique subdirectory for storing
  394.   attached files.  The subdirectory need not be included in the DLPATH.LST file
  395.   since PCBoard will be able to locate the file attachment.  However, it may be
  396.   included in the DLPATH.LST if you want others, who are not reading the
  397.   message, to be able to download the file if they know the name.
  398.  
  399.   Q: Will the full path of the attached file be stored in the message header?
  400.  
  401.   A: No.  By storing only the name of the file, the sysop may change the
  402.   configuration at any time without having to process the message base to make
  403.   the change.  In other words, the sysop could move attached files from one
  404.   drive to another with a simple change in configuration.
  405.  
  406.   Q: Will protocol transfers be allowed for attached uploads?  How about the
  407.   message text itself?
  408.  
  409.   A: Yes to both questions.  The user can upload message text using a transfer
  410.   protocol other than ASCII.  If the message is to be saved with an attached
  411.   file then the caller will be prompted for the upload and, again, a protocol
  412.   transfer will take place.
  413.