rfc3072.txt

RFC 的详细文档！

   while (x.rc == 0) // 0 == ok, rc will set by the SDXF functions
   {
     switch (x.chunkID)
     {
       case 3302:
         x.extract (data1, maxLength1);
                   // extr. 1st chunk into data1
         break;

       case 3303:
         x.extract (data2, maxLength2);
                   // extr. 2nd chunk into data2
         break;

       case 3304:  // we know this is a structure
         x.enter (); // enters the inner structure

         while (x.rc == 0) // inner loop
         {
           switch (x.chunkID)
           {
             case 3305:
               x.extract (data3, maxLength3);
                         // extr. the chunk inside struct.



Wildgrube                    Informational                      [Page 7]

RFC 3072            Structured Data Exchange Format           March 2001


               break;
             case 3306:
               x.extract (data4, maxLength4);
                         // extr. 2nd chunk inside struct.
               break;
           }
           x.next (); // returns x.rc == 1 at end of structure
         } // end-while
         break;

       case 3307:
         x.extract (data5, maxLength5);
                   // extract last chunk into data
         break;
       // default: none - ignore unknown chunks !!!

     } // end-switch
     x.next (); // returns x.rc = 1 at end of structure
   } // end-while

4. Platform independence

   The very most of the computer platforms today have a 8-Bits-in-a-Byte
   architecture, which enables data exchange between these platforms.
   But there are two significant points in which platforms may be
   different:

   a) The representation of binary numerical (the short and long int and
      floats).

   b) The representation of characters (ASCII/ANSI vs. EBCDIC)

   Point (a) is the phenomenon of "byte swapping": How is a short int
   value 259 = 0x0103 = X'0103' be stored at address 4402?

   The two flavours are:

   4402 4403
   01   03    the big-endian, and
   03   01    the little-endian.

   Point (b) is represented by a table of the assignment of the 256
   possible values of a Byte to printable or control characters.  (In
   ASCII the letter "A" is assigned to value (or position) 0x41 = 65, in
   EBCDIC it is 0xC1 = 193.)






Wildgrube                    Informational                      [Page 8]

RFC 3072            Structured Data Exchange Format           March 2001


   The solution of these problems is to normalize the data:

   We fix:

   (a) The internal representation of binary numerals are 2-complements
       in big-endian order.

   (b) The internal representation of characters is ISO 8859-1 (also
       known as Latin 1).

   The fixing of point (b) should be regarded as a first strike.  In
   some environment 8859-1 seems not to be the best choice, in a greek
   or russian environment 8859-5 or 8859-7 are appropriate.

   Nevertheless, in a specific group (or world) of applications, that is
   to say all the applications which wants to interchange data with a
   defined protocol (via networking or diskette or something else), this
   internal character table must be unique.

   So a possibility to define a translation table (and his inversion)
   should be given.

   Important: You construct a SDXF chunk not for a specific addressee,
   but you adapt your data into a normalized format (or network format).

   This adaption is not done by the programmer, it will be done by the
   create and extract function.  An administrator has take care of
   defining the correct translation tables.

5. Compression

   As stated in 2.5 there is a flag bit which declares that the
   following data (elementary or structured) are compressed.  This data
   is not further interpretable until it is decompressed.  Compression
   is transparently done by the SDXF functions: "create" does the
   compression for elementary chunks, "leave" for structured chunks,
   "extract" does the decompression for elementary chunks, "enter" for
   structured chunks.

   Transparently means that the programmer has only to tell the SDXF
   functions that he want compress the following chunk(s).

   For choosing between different compression methods and for
   controlling the decompressed (original) length, there is an
   additional definition:






Wildgrube                    Informational                      [Page 9]

RFC 3072            Structured Data Exchange Format           March 2001


   After the chunk header for a compressed chunk, a compression header
   is following:

   +-----------------------+---------------+---------------->
   |      chunk header     | compr. header | compressed data
   +---+---+---+---+---+---+---+---+---+---+---------------->
   |chunkID|flg|   length  |md | orglength |
   +---+---+---+---+---+---+---+---+---+---+---------------->

   -  'orglength' is the original (decompressed) length of the data.

   -  'md' is the "compression method": Two methods are described here:

      #  method 01 for a simple (fast but not very effective)
         "Run Length 1" or "Byte Run 1" algorithm.  (More then two
         consecutive identical characters are replaced by the number of
         these characters and the character itself.)

         more precisely:

         The compressed data consists of several sections of various
         length.  Every section starts with a "counter" byte, a signed
         "tiny" (8 bit) integer, which contains a length information.

         If this byte contains the value "n",
         with n >= 0 (and n <128), the next n+1 bytes will be taken
         unchanged;
         with n < 0 (and n > -128), the next byte will be replicated
         -n+1 times;
         n = -128 will be ignored.

         Appending blanks will be cutted in general.  If these are
         necessary, they can be reconstructed while "extract"ing with
         the parameter field "filler" (see 8.2.1) set to space
         character.

      #  method 02 for the wonderful "deflate" algorithm which comes
         from the "zip"-people.
         The authors are:
         Jean-loup Gailly (deflate routine),
         Mark Adler (inflate routine), and others.

         The deflate format is described in [DEFLATE].

      The values for the compression method number are maintained by
      IANA, see chap. 12.1.





Wildgrube                    Informational                     [Page 10]

RFC 3072            Structured Data Exchange Format           March 2001


6. Encryption

   As stated in 2.5 there is a flag bit which declares that the
   following data (elementary or structured) is encrypted.  This data is
   not interpretable until it is decrypted.  En/Decryption is
   transparently done by the SDXF functions, "create" does the
   encryption for elementary chunks, "leave" for structured chunks,
   "extract" does the decryption for elementary chunks, "enter" for
   structured chunks.  (Yes it sounds very similar to chapter 5.)  More
   then one encryption method for a given range of applications is not
   very reasonable. Some encryption algorithms work with block ciphering
   algorithms. That means that the length of the data to encrypt must be
   rounded up to the next multiple of this block length. This blocksize
   (zero means non-blocking) is reported by the encryption interface
   routine (addressed by the option field *encryptProc, see chapter 8.5)
   with mode=3. If blocking is used, at least one byte is added, the
   last byte of the lengthening data contains the number of added bytes
   minus one. With this the decryption interface routine can calculate
   the real data length.

   If an application (or network connect handshaking protocol) needs to
   negotiate an encryption method it should be used a method number
   maintained by IANA, see chap. 12.2.

   Even the en/decryption is done transparently, an encryption key
   (password) must be given to the SDXF functions.  Encryption is done
   after translating character data into, decryption is done before
   translation from the internal ("network-") format.

   If both, encryption and compression are applied on the same chunk,
   compression is done first - compression on good encrypted data (same
   strings appears as different after encryption) tends to zero
   compression rates.

7. Arrays

   An array is a sequence of chunks with identical chunk-ID, length and
   data type.

   At first a hint: in principle a special definition in SDXF for such
   an array is not really necessary:

   It is not forbidden that there are more than one chunk with equal
   chunk-ID within the same structured chunk.

   Therefore with a sequence of SDX_next / SDX_extract calls one can
   fill the destination array step by step.




Wildgrube                    Informational                     [Page 11]

RFC 3072            Structured Data Exchange Format           March 2001


   If there are many occurrences of chunks with the same chunk-ID (and a
   comparative small length), the overhead of the chunk-packages may be
   significant.

   Therefore the array flag is introduced.  An array chunk has only one
   chunk header for the complete sequence of elementary chunks.  After
   the chunk header for an array chunk, an array header is following:

   This is a short integer (big endian!) which contains the number of
   the array elements (CT).  Every element has a fixed length (EL), so
   the chunklength (CL) is CL = EL * CT + 2.

   The data elements follows immediately after the array header.

   The complete array will be constructed by SDX_create, the complete
   array will be read by SDX_extract.

   The parameter fields (see 8.2.1) 'dataLength' and 'count' are used
   for the SDXF functions 'extract' and 'create':

   Field 'dataLength' is the common length of the array elements,
   'count' is the actual dimension of the array for 'create' (input).

   For the 'extract' function 'count' acts both as an input and output
   parameter:

   Input : the maximum dimension
   output: the actual array dimension.

   (If output count is greater than input count, the 'data cutted'
   warning will be responded and the destination array is filled up to
   the maximum dimension.)

8. Description of the SDXF functions

8.1 Introduction

   Following the principles of Object Oriented Programming, not only the
   description of the data is necessary, but also the functions which
   manipulate data - the "methods".

   For the programmer knowing the methods is more important than knowing
   the data structure, the methods has to know the exact specifications
   of the data and guarantees the consistence of the data while creating
   them.






Wildgrube                    Informational                     [Page 12]

RFC 3072            Structured Data Exchange Format           March 2001


   A SDXF object is an instance of a parameter structure which acts as a
   programming interface.  Especially it points to an actual SDXF data
   chunk, and, while processing on this data, there is a pointer to the
   actual inner chunk which will be the focus for the next operation.

   The benefit of an exact interface description is the same as using
   for example the standard C library functions: By using standard
   interfaces your code remains platform independent.

8.2 Basic definitions

8.2.1 The SDXF Parameter structure

   All SDXF access functions need only one parameter, a pointer to the
   SDXF parameter structure:

   First 3 prerequisite definitions:

   typedef short int      ChunkID;
   typedef unsigned char  Byte;

   typedef struct Chunk
   {
     ChunkID    chunkID;
     Byte       flags;
     char       length [3];
     Byte       data;
   } Chunk;

   And now the parameter structure:

   typedef struct
   {
     ChunkID  chunkID;       // name (ID) of Chunk
     Byte    *container;     // pointer to the whole Chunk
     long     bufferSize;    // size of container
     Chunk   *currChunk;     // pointer to actual Chunk
     long     dataLength;    // length of data in Chunk
     long     maxLength;     // max. length of Chunk for SDX_extract
     long     remainingSize; // rem. size in cont. after SDX_create
     long     value;         // for data type numeric
     double   fvalue;        // for data type float
     char    *function;      // name of the executed SDXF function
     Byte    *data;          // pointer to Data
     Byte    *cryptkey;      // pointer to Crypt Key
     short    count;         // (max.) number of elements in an array
     short    dataType;      // Chunk data type / init open type
     short    ec;            // extended return-code



Wildgrube                    Informational                     [Page 13]