rfc3072.txt

RFC 的详细文档！


RFC 3072            Structured Data Exchange Format           March 2001


     short    rc;            // return-code
     short    level;         // level of hierarchy
     char     filler;        // filler char for SDX_extract
     Byte     encrypt;       // Indication if data to encrypt (0 / 1)
     Byte     compression;   // compression method
                             //   (00=none, 01=RL1, 02=zip/deflate)
   } SDX_obj, *SDX_handle;

   Only the "public" fields of the parameter structure which acts as
   input and output for the SDXF functions is described here.  A given
   implementation may add some "private" fields to this structure.

8.2.2 Basic Functions

   All these functions works with a SDX_handle as the only formal
   parameter.  Every function returns as output ec and rc as a report of
   success.  For the values for ec, rc and dataType see chap. 8.4.

    1. SDX_init : Initialize the parameter structure.

         input : container, dataType, bufferSize (for dataType =
                 SDX_NEW only)
         output: currChunk, dataLength (for dataType = SDX_OLD only),
                 ec, rc,
                 the other fields of the parameter structure will be
                 initialized.

    2. SDX_enter : Enter a structured chunk.
       You can access the first chunk inside this structured chunk.
         input : none
         output: currChunk, chunkID, dataLength, level, dataType,
                 ec, rc

    3. SDX_leave : Leave the actual entered structured chunk.
         input : none
         output: currChunk, chunkID, dataLength, level, dataType,
                 ec, rc

    4. SDX_next : Go to the next chunk inside a structured chunk.
         input : none
         output: currChunk, chunkID, dataLength, dataType, count, ec, rc

        At the end of a structured chunk SDX_next returns rc =
        SDX_RC_failed and ec = SDX_EC_eoc (end of chunk)
        The actual structured chunk is SDX_leave'd automatically.






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


    5. SDX_extract : Extract data of the actual chunk.
       (If actual chunk is structured, only a copy is done, elsewhere
       the data is converted to host format.)
       input / output depends on the dataType:

       if dataType is structured, binary or char:
         input : data, maxLength, count, filler
         output: dataLength, count, ec, rc

       if dataType is numeric (float resp.):
         input : none
         output: value (fvalue resp.), ec, rc

    6. SDX_select : Go to the (next) chunk with a given chunkID.
         input : chunkID
         output: currChunk, dataLength, dataType, ec, rc

    7. SDX_create : Creating a new chunk (at the end of the actual
       structured chunk).
         input : chunkID, dataLength, data, (f)value, dataType,
                 compression, encrypt, count
         update: remainingSize, level
         output: currChunk, dataLength, ec, rc

    8. SDX_append : Append a complete chunk at the end of the actual
       structured chunk).
         input : data, maxLength, currChunk
         update: remainingSize, level
         output: chunkID, chunkLength, maxLength, dataType, ec, rc

8.3 Definitions for C++

   This is the specification of the SDXF class in C++: (The type 'Byte'
   is defined as "unsigned char" for bitstrings, opposed to "signed
   char" for character strings)

   class C_SDXF
   {
     public:

     // constructors and destructor:
     C_SDXF  ();                          // dummy
     C_SDXF  (Byte *cont);                // old container
     C_SDXF  (Byte *cont, long size);     // new container
     C_SDXF  (long size);                 // new container
     ~C_SDXF ();
     // methods:




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


     void init  (void);                   // old container
     void init  (Byte *cont);             // old container
     void init  (Byte *cont, long size);  // new container
     void init  (long size);              // new container

     void enter   (void);
     void leave   (void);
     void next    (void);
     long extract (Byte *data, long length);    // chars, bits
     long extract (void);                       // numeric data
     void create  (ChunkID);                    // structured
     void create  (ChunkID, long value);        // numeric
     void create  (ChunkID, double fvalue);     // float
     void create  (ChunkID, Byte *data, long length);// binary
     void create  (ChunkID, char *data);             // chars
     void set_compression (Byte compression_method);
     void set_encryption  (Byte *encryption_key);

     // interface:

     ChunkID  id;        // see 8.4.1
     short    dataType;  // see 8.4.2
     long     length;    // length of data or chunk

     long     value;
     double   fvalue;
     short    rc;  // the raw return code       see 8.4.3
     short    ec;  // the extended return code  see 8.4.4

     protected:
     // implementation dependent ...

   };

8.4 Common Definitions:

8.4.1 Definition of ChunkID:

   typedef short ChunkID;

8.4.2 Values for dataType:

   SDX_DT_inconsistent     = 0
   SDX_DT_structured       = 1
   SDX_DT_binary           = 2
   SDX_DT_numeric          = 3
   SDX_DT_char             = 4
   SDX_DT_float            = 5



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


   SDX_DT_UTF8             = 6

    data types for SDX_init:
   SDX_OLD                 = 1
   SDX_NEW                 = 2

8.4.3 Values for rc:

   SDX_RC_ok               = 0
   SDX_RC_failed           = 1
   SDX_RC_warning          = 1
   SDX_RC_illegalOperation = 2
   SDX_RC_dataError        = 3
   SDX_RC_parameterError   = 4
   SDX_RC_programError     = 5
   SDX_RC_noMemory         = 6

8.4.4 Values for ec:

   SDX_EC_ok              =  0
   SDX_EC_eoc             =  1 // end of chunk
   SDX_EC_notFound        =  2
   SDX_EC_dataCutted      =  3
   SDX_EC_overflow        =  4
   SDX_EC_wrongInitType   =  5
   SDX_EC_comprerr        =  6 // compression error
   SDX_EC_forbidden       =  7
   SDX_EC_unknown         =  8
   SDX_EC_levelOvflw      =  9
   SDX_EC_paramMissing    = 10
   SDX_EC_magicError      = 11
   SDX_EC_not_consistent  = 12
   SDX_EC_wrongDataType   = 13
   SDX_EC_noMemory        = 14
   SDX_EC_error           = 99 // rc is sufficiently

8.5 Special functions

   Besides the basic definitions there is a global function
   (SDX_getOptions) which returns a pointer to a global table of
   options.

   With the help of these options you can adapt the behaviour of SDXF.
   Especially you can define an alternative pair of translation tables
   or an alternative function which reads these tables from an external
   resource (p.e. from disk).





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


   Within this table of options there is also a pointer to the function
   which is used for encryption / decryption: You can install your own
   encryption algorithm by setting this pointer.

   The options pointer is received by:

   SDX_TOptions *opt = SDX_getOptions ();

   With:

   typedef struct
   {
    Byte            *toHost;        // Trans tab net -> host
    Byte            *toNet;         // Trans tab host -> net
    int              maxlevel;      // highest possible level
    int              translation;   // translation net <-> host
                                    // is in effect=1 or not=0
    TEncryptProc    *encryptProc;   // alternate encryption routine
    TGetTablesProc  *getTablesProc; // alternate routine defining
                                    // translation Tables
    TcvtUTF8Proc    *convertUTF8;   // routine to convert to/from UTF-8
   }  SDX_TOptions;

   typedef long TencryptProc (
     int   mode,   // 1= to encrypt, 2= to decrypt, 3= encrypted length
     Byte *buffer, // data to en/decrypt
     long  len,    // len: length of buffer
     char *passw); // Password

    // returns length of en/de-crypted data
    // (parameter buffer and passw are ignored for mode=3)
    // returns blocksize for mode=3 and len=0.
    // blocksize is zero for non-blocking algorithms

   typedef int TGetTablesProc (Byte **toNet, Byte **toHost);
    // toNet, toHost: pointer to output params.  Both params
    // points to translation tables of 256 Bytes.
    // returns success: 1 = ok, 0 = error.

   typedef int TcvtUTF8Proc
   ( int   mode,     // 1 = to UTF-8, 2 = from UTF-8
     Byte *target, int *targetlength,  // output
     Byte *source, int sourcelength);  // input
   // targetlength contains maximal size as input param.
   // returns success: 1 = ok, 0 = no conversion






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


9. 'Support' of UTF-8.

   Many systems supports [UTF-8] as a character format for transferred
   data.  The benefit is that no fixing of a specific character set for
   an application is needed because the set of 'all' characters is used,
   represented by the 'Universal Character Set' UCS-2 [UCS], a double
   byte coding for characters.

   SDXF does not really deal with UTF-8 by itself, there are many
   possibilities to interprete an UTF-8 sequence:  The application may:

   -  reconstruct the UCS-2 sequence,
   -  accepts only the pure ASCII character and maps non-ASCII to a
      special 'non-printable' character.
   -  target is pure ASCII, non-ASCII is replaced in a senseful manner
      (French accented vowels replaced by vowels without accents, etc.).
   -  target is a specific ANSI character set, the non-ASCII chars are
      mapped as possible, other replaced to a 'non-printable'.
   -  etc.

   But SDXF offers an interface for the 'extract' and 'create'
   functions:

   A function pointer may be specified in the options table to maintain
   this possibility (see 8.5).  Default for this pointer is NULL: No
   further conversions are done by SDXF, the data are copied 'as is', it
   is treated as a bit string as for data type 'binary'.

   If this function is specified, it is used by the 'create' function
   with the 'toUTF8' mode, and by the 'extract' function with the '
   fromUTF8' mode.  The invoking of these functions is done by SDXF
   transparently.

   If the function returns zero (no conversion) SDXF copies the data
   without conversion.

10. Security Considerations

   Any corruption of data in the chunk headers denounce the complete
   SDXF structure.

   Any corruption of data in a encrypted or compressed SDXF structure
   makes this chunk unusable.  An integrity check after decryption or
   decompression should be done by the "enter" function.

   While using TCP/IP (more precisely: IP) as a transmission medium we
   can trust on his CRC check on the transport layer.




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


11. Some general hints

   1. A consistent construction of a SDXF structure is done if every
      "create" to a structured chunk is closed by a paired "leave".
      While a structured chunk is under construction, his data type is
      set to zero - that means: this chunk is inconsistent.  The
      SDX_leave function sets the datatype to "structured".

   2. While creating an elementary chunk a platform dependent
      transformation to a platform independent format of the data is
      performed - at the end of construction the content of the buffer
      is ready to transport to another site, without any further
      translation.

   3. As you see no data definition in your programming language is
      needed for to construct a specific SDXF structure.  The data is
      created dynamically by function calls.

   4. With SDXF as a base you can define protocols for client / server
      applications.  These protocols may be extended in downward
      compatibility manner by following two rules:

      Rule 1: Ignore unknown chunkIDs.

      Rule 2: The sequence of chunks should not be significant.