The "natural" structure of a file will depend on which host
   stores the file.  A source-code file will usually be stored on
   an IBM Mainframe in fixed length records but on a DEC TOPS-20
   as a stream of characters partitioned into lines, for example
   by <CRLF>.  If the transfer of files between such disparate
   sites is to be useful, there must be some way for one site to
   recognize the other's assumptions about the file.

   With some sites being naturally file-oriented and others
   naturally record-oriented there may be problems if a file with
   one structure is sent to a host oriented to the other.  If a
   text file is sent with record-structure to a host which is file
   oriented, then that host should apply an internal
   transformation to the file based on the record structure.
   Obviously, this transformation should be useful, but it must
   also be invertible so that an identical file may be retrieved
   using record structure.

   In the case of a file being sent with file-structure to a
   record-oriented host, there exists the question of what
   criteria the host should use to divide the file into records
   which can be processed locally.  If this division is necessary,
   the FTP implementation should use the end-of-line sequence,

   <CRLF> for ASCII, or <NL> for EBCDIC text files, as the
   delimiter.  If an FTP implementation adopts this technique, it
   must be prepared to reverse the transformation if the file is
   retrieved with file-structure.
*/

/** \fn static const CStructure nsFTP::CStructure::File()
   File structure is the default to be assumed if the STRUcture
   command has not been used.
   In file-structure there is no internal structure and the
   file is considered to be a continuous sequence of data
   bytes.
*/
/** \fn static const CStructure nsFTP::CStructure::Record()
   Record structures must be accepted for "text" files (i.e.,
   files with TYPE ASCII or EBCDIC) by all FTP implementations.
   In record-structure the file is made up of sequential
   records.
*/
/** \fn static const CStructure nsFTP::CStructure::Page()
   To transmit files that are discontinuous, FTP defines a page
   structure.  Files of this type are sometimes known as
   "random access files" or even as "holey files".  In these
   files there is sometimes other information associated with
   the file as a whole (e.g., a file descriptor), or with a
   section of the file (e.g., page access controls), or both.
   In FTP, the sections of the file are called pages.

   To provide for various page sizes and associated
   information, each page is sent with a page header.  The page
   header has the following defined fields:

      - Header Length\n
         The number of logical bytes in the page header
         including this byte.  The minimum header length is 4.

      - Page Index\n
         The logical page number of this section of the file.
         This is not the transmission sequence number of this
         page, but the index used to identify this page of the
         file.

      - Data Length\n
         The number of logical bytes in the page data.  The
         minimum data length is 0.

      - Page Type\n
         The type of page this is.  The following page types
         are defined:

<PRE>         0 = Last Page
            This is used to indicate the end of a paged
            structured transmission.  The header length must
            be 4, and the data length must be 0.

         1 = Simple Page
            This is the normal type for simple paged files
            with no page level associated control
            information.  The header length must be 4.

         2 = Descriptor Page
            This type is used to transmit the descriptive
            information for the file as a whole.

         3 = Access Controlled Page
            This type includes an additional header field
            for paged files with page level access control
            information.  The header length must be 5.</PRE>

      - Optional Fields\n
         Further header fields may be used to supply per page
         control information, for example, per page access
         control.

   All fields are one logical byte in length.  The logical byte
   size is specified by the TYPE command.  See Appendix I for
   further details and a specific case at the page structure.

   A note of caution about parameters:  a file must be stored and
   retrieved with the same parameters if the retrieved version is to

   be identical to the version originally transmitted.  Conversely,
   FTP implementations must return a file identical to the original
   if the parameters used to store and retrieve a file are the same.
*/

/** \class nsFTP::CTransferMode
   The next consideration in transferring data is choosing the
   appropriate transmission mode.  There are three modes: one which
   formats the data and allows for restart procedures; one which also
   compresses the data for efficient transfer; and one which passes
   the data with little or no processing.  In this last case the mode
   interacts with the structure attribute to determine the type of
   processing.  In the compressed mode, the representation type
   determines the filler byte.

   All data transfers must be completed with an end-of-file (EOF)
   which may be explicitly stated or implied by the closing of the
   data connection.  For files with record structure, all the
   end-of-record markers (EOR) are explicit, including the final one.
   For files transmitted in page structure a "last-page" page type is
   used.

   NOTE:  In the rest of this section, byte means "transfer byte"
   except where explicitly stated otherwise.

   For the purpose of standardized transfer, the sending host will
   translate its internal end of line or end of record denotation
   into the representation prescribed by the transfer mode and file
   structure, and the receiving host will perform the inverse
   translation to its internal denotation.  An IBM Mainframe record
   count field may not be recognized at another host, so the
   end-of-record information may be transferred as a two byte control
   code in Stream mode or as a flagged bit in a Block or Compressed
   mode descriptor.  End-of-line in an ASCII or EBCDIC file with no
   record structure should be indicated by <CRLF> or <NL>,
   respectively.  Since these transformations imply extra work for
   some systems, identical systems transferring non-record structured
   text files might wish to use a binary representation and stream
   mode for the transfer.
*/

/** \fn static const CTransferMode nsFTP::CTransferMode::Stream()
   The data is transmitted as a stream of bytes.  There is no
   restriction on the representation type used; record structures
   are allowed.

   In a record structured file EOR and EOF will each be indicated
   by a two-byte control code.  The first byte of the control code
   will be all ones, the escape character.  The second byte will
   have the low order bit on and zeros elsewhere for EOR and the
   second low order bit on for EOF; that is, the byte will have
   value 1 for EOR and value 2 for EOF.  EOR and EOF may be
   indicated together on the last byte transmitted by turning both
   low order bits on (i.e., the value 3).  If a byte of all ones
   was intended to be sent as data, it should be repeated in the
   second byte of the control code.

   If the structure is a file structure, the EOF is indicated by
   the sending host closing the data connection and all bytes are
   data bytes.
*/

/** \fn static const CTransferMode nsFTP::CTransferMode::Block()
   The file is transmitted as a series of data blocks preceded by
   one or more header bytes.  The header bytes contain a count
   field, and descriptor code.  The count field indicates the
   total length of the data block in bytes, thus marking the
   beginning of the next data block (there are no filler bits).
   The descriptor code defines:  last block in the file (EOF) last
   block in the record (EOR), restart marker (see the Section on
   Error Recovery and Restart) or suspect data (i.e., the data
   being transferred is suspected of errors and is not reliable).
   This last code is NOT intended for error control within FTP.
   It is motivated by the desire of sites exchanging certain types
   of data (e.g., seismic or weather data) to send and receive all
   the data despite local errors (such as "magnetic tape read
   errors"), but to indicate in the transmission that certain
   portions are suspect).  Record structures are allowed in this
   mode, and any representation type may be used.

   The header consists of the three bytes.  Of the 24 bits of
   header information, the 16 low order bits shall represent byte
   count, and the 8 high order bits shall represent descriptor
   codes as shown below.

   Block Header
<PRE>
      +----------------+----------------+----------------+
      | Descriptor     |    Byte Count                   |
      |         8 bits |                      16 bits    |
      +----------------+----------------+----------------+
</PRE>
   The descriptor codes are indicated by bit flags in the
   descriptor byte.  Four codes have been assigned, where each
   code number is the decimal value of the corresponding bit in
   the byte.
<PRE>
      Code     Meaning

        128     End of data block is EOR
         64     End of data block is EOF
         32     Suspected errors in data block
         16     Data block is a restart marker
</PRE>
   With this encoding, more than one descriptor coded condition
   may exist for a particular block.  As many bits as necessary
   may be flagged.

   The restart marker is embedded in the data stream as an
   integral number of 8-bit bytes representing printable
   characters in the language being used over the control
   connection (e.g., default--NVT-ASCII).  <SP> (Space, in the
   appropriate language) must not be used WITHIN a restart marker.

   For example, to transmit a six-character marker, the following
   would be sent:
<PRE>
      +--------+--------+--------+
      |Descrptr|  Byte count     |
      |code= 16|             = 6 |
      +--------+--------+--------+

      +--------+--------+--------+
      | Marker | Marker | Marker |
      | 8 bits | 8 bits | 8 bits |
      +--------+--------+--------+

      +--------+--------+--------+
      | Marker | Marker | Marker |
      | 8 bits | 8 bits | 8 bits |
      +--------+--------+--------+
</PRE>
*/

/** \fn static const CTransferMode nsFTP::CTransferMode::Compressed()
   There are three kinds of information to be sent:  regular data,
   sent in a byte string; compressed data, consisting of
   replications or filler; and control information, sent in a
   two-byte escape sequence.  If n>0 bytes (up to 127) of regular
   data are sent, these n bytes are preceded by a byte with the
   left-most bit set to 0 and the right-most 7 bits containing the
   number n.

   Byte string:
<PRE>
         1       7                8                     8
      +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+     +-+-+-+-+-+-+-+-+
      |0|       n     | |    d(1)       | ... |      d(n)     |
      +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+     +-+-+-+-+-+-+-+-+
                                    ^             ^
                                    |---n bytes---|
                                          of data
</PRE>
   String of n data bytes d(1),..., d(n)
   Count n must be positive.

   To compress a string of n replications of the data byte d, the
   following 2 bytes are sent:

   Replicated Byte:
<PRE>
         2       6               8
      +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
      |1 0|     n     | |       d       |
      +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
</PRE>