doc/README.serialization

         HOW TO USE SERIALIZATION / DE-SERIALIZATION
		==============================================

   Serialization/deserialization of unsignedByte, unsignedShort,
unsignedInt, boolean and string built-n XML Schema types is now supported.
It is possible to serialize/deserialize structures, static and dynamic
size arrays constructed from these types.

  For example, let us have the following schema:
  <xsd:element name="SAMPLE">
     <xsd:complexType>
       <xsd:sequence>
         <xsd:element name="STRING" type="xsd:string"/>
         <xsd:element name="BOOL" type="xsd:boolean"/>
         <xsd:element name="BYTE" type="xsd:unsignedByte"/>
         <xsd:element name="SHORT" type="xsd:unsignedShort"/>
         <xsd:element name="INT" type="xsd:unsignedInt"/>
         <xsd:element name="SHORTS" type="xsd:unsignedShort" minOccurs="3" maxOccurs="3"/>
         <xsd:element name="INTS" type="xsd:unsignedInt" minOccurs="0" maxOccurs="5"/>
         <xsd:element ref="FOO"  maxOccurs="unbounded"/>
       </xsd:sequence>
     </xsd:complexType>
  </xsd:element>
  <xsd:element name="FOO">
     <xsd:complexType>
       <xsd:sequence>
         <xsd:element name="FooSTRING" type="xsd:string"/>
         <xsd:element name="FooINT" type="xsd:unsignedInt"/>
         <xsd:element name="FooBOOL" type="xsd:boolean"/>
       </xsd:sequence>
     </xsd:complexType>
  </xsd:element>


  Each complex element is represented in the C program by 2 objects - target
  structure (TS) definition and type description object (TDO) - the null
  terminated array of type XmlSerializerInfo elements. The following name
  convention exists: TDO for Foo is named Foo_TypeInfo.
  For our example these structures look the following:

   target structures:

   typedef struct {
       XML_TYPE_STR     FooString;
       XML_TYPE_UINT32  FooInt;
       XML_TYPE_BOOL    FooBoolean;
   } Foo;

   typedef struct {
       XML_TYPE_STR     String;
       XML_TYPE_BOOL    Boolean;
       XML_TYPE_UINT8   Byte;
       XML_TYPE_UINT16  Short;
       XML_TYPE_UINT32  Int;
       XML_TYPE_UINT16  Shorts[3];
       XML_TYPE_DYN_ARRAY  Ints;
       XML_TYPE_DYN_ARRAY  Foos;
  } Sample;

  Note, that the field 'Shorts' in Sample is defined as built-in array because
  the number of elements in schema is strictly defined. Elements Ints
  and Foos are defined as dynamic arrays because the number of these elements
 in the document is variable.

  For each TS an TDO is defined. Each TDS is defined by the sequence of
  defines described in wsman-xml-serializer.h. The order of defines in TDO
  must be same as the order of fields in TS.

 SER_START_ITEMS("FOO", Foo)
           // This is the beginning of the description. The first argument is the
           // name of an element in the XML schema, the second one is the name
           // of the TS type.
    SER_STR("FooSTRING", 1),
    SER_UINT32("FooINT", 1),
    SER_BOOL("FooBOOL", 1),
           // These 3 defines are for string, unsignedInt and boolean XML types
           // accordingly. The first argument is the name of an element in the XML
           // schema, the second one is the number of elements.
 SER_END_ITEMS("FOO", Foo);
           // This Define completes the definition. The arguments are same as
           // for SER_START_ITEMS.

  So if we define The TDO for Foo type. It looks like:
      XmlSerializerInfo Foo_TypeInfo[] = {
        ................
      };
  There are some Defines to add XmlSerializerInfo's for basic types XML_TYPE_UINT8,
  XML_TYPE_UINT16, XML_TYPE_UINT32, XML_TYPE_BOOL and XML_TYPE_STR:
      SER_TYPEINFO_UINT8;
      SER_TYPEINFO_UINT16;
      SER_TYPEINFO_UINT32;
      SER_TYPEINFO_BOOL;
      SER_TYPEINFO_STR;
  If you use dymanic arrays of basic types you must define the corespondent
  XmlSerializerInfo before defining TDO including this dynamic array. You will
  refer to these TDOs in SER_DYN_ARRAY define and use the fourth argument for
  these types uint8, uint16, uint32, bool and string as the last argument (see
  below). 

 Let's do the same for the Sample type.

   SER_START_ITEMS(sample)
      SER_STR("STRING", 1),
      SER_BOOL("BOOL", 1),
      SER_UINT8("BYTE", 1),
      SER_UINT16("SHORT", 1),
      SER_UINT32("INT", 1),
      SER_UINT16("SHORTS", 3),
      SER_DYN_ARRAY("INTS", 0, 5, uint32),
           // This dynamic array describes XML element INTS of type unsignedInt
           // with minOccurs=0 and maxOccurs=5.
      SER_DYN_ARRAY("FOOS", 1, 0, Foo),
           // Dynamic array of Foo type elements. maxOccures=0 means
           // "unbounded" in XML schema
   SER_END_ITEMS(sample);


  These objects can be used in ws_serialize() and ws_deserialize() API.

  There are 2 sets of defines SER_IN_* and SER_OUT_*. These defines are used
  if you want to skip the elements while de-serialization(serialization). If
  define SER_INOUT_* is used the element is skipped always.

  If element name is a QName (with name space prefix) the
      SER_NS_*(ns, name, ..) define set must be used.