

>WBXML Library>
    by Aymerick Jhanne
    
WBXML Library
C library for handling WBXML content
Aymerick Jhanne
Copyright  2003 Aymerick Jhanne
2003
Revision History Revision Beta 0.7.0 2003-03-20 First Draft for the WBXML Library 0.7.0 Revision Beta 0.7.1 2003-03-21 First Draft for the WBXML Library 0.7.1 (not packaged - still leaks explanation of WBXMLTree, WBXMLTag and WBXMLAttribute interfaces) Abstract

            WBXML Library is a C library for handling WBXML content.
        
Table of Contents
1. #overviewOverview 1.1. #d3e41Components 1.2. #d3e64Supported Languages 1.3. #d3e182Project 1.4. #d3e191Code Documentation 2. #installBuilding and Installing 2.1. #d3e198Linux 2.2. #d3e224Windows 3. #usingUsing WBXML Library 3.1. #d3e246File convertion Tools (xml2wbxml, wbxml2xml) 3.2. #d3e254Buffer convertion Library (libwbxml2_conv) 3.3. #d3e262Low level WBXML Parser and Encoder (libwbxml2) 4. #referenceReference 4.1. #d3e333libwbxml2 4.1.1. #d3e335WBXML Encoder 4.1.1.1. #d3e337Encoder Creation 4.1.1.2. #d3e365Encoder Initialization when generating WBXML or XML 4.1.1.3. #d3e394Encoder Initialization when generating WBXML 4.1.1.4. #d3e410Encoder Initialization when generating XML 4.1.1.5. #d3e444Encoding Functions 4.1.1.6. #d3e485Example 4.1.2. #d3e490WBXML Parser 4.1.2.1. #d3e496Parse to WBXML Tree 4.1.2.2. #d3e513Parse with User Defined Callbacks 4.1.3. #d3e765WBXML Tree 4.2. #d3e768libwbxml2_conv 4.2.1. #d3e771XML to WBXML Convertion 4.2.1.1. #d3e773Prototype 4.2.1.2. #d3e788XML2WBXMLParameters Structure 4.2.1.3. #d3e792Example 4.2.2. #d3e797WBXML to XML Convertion 4.2.2.1. #d3e799Prototype 4.2.2.2. #d3e814WBXML2XMLParameters Structure 4.2.2.3. #d3e818Example 4.3. #d3e823Tools 4.3.1. #d3e826xml2wbxml 4.3.2. #d3e843wbxml2xml List of Examples
4.1. #d3e362WBXML Encoder Creation/Destruction 4.2. #d3e487WBXML Encoder Use 4.3. #d3e540WBXML Parser Creation/Destruction 4.4. #d3e762WBXML Parser use 4.5. #d3e794XML to WBXML Convertion 4.6. #d3e820WBXML to XML Convertion Chapter1.Overview
Table of Contents
1.1. #d3e41Components 1.2. #d3e64Supported Languages 1.3. #d3e182Project 1.4. #d3e191Code Documentation 1.1.Components

            The WBXML Library consists of 2 libraries:
            
libwbxml2
                            The main library, which contains the WBXML Parser and
                            the WBXML Encoder. This is a standalone library.
                        
libwbxml2_conv
                            A wrapper arround libwbxml2 to convert from XML to WBXML and
                            from WBXML to XML. This is linked with libwbxml2 and 
http://expat.sourceforge.net/Expat .
                        

        
            
            Two tools are also provided:
            
xml2wbxml
                            Converts a XML document to a WBXML document.
                        
wbxml2xml
                            Converts a WBXML document to a XML document.
                        
          
        
1.2.Supported Languages

            

                        
http://www.wapforum.org/WAP Forum  Specifications
                        

                                    
http://www.wapforum.org/what/technical_1_0.htmWAP 1.0 
                                    

                                                WBXML 1.0 - WBXML-30-Apr-98.pdf 
(Tested)
                                            

                                                WML 1.0 - WML-30-Apr-98.pdf 
(Untested)
                                            

                                                WTA 1.0 - wta-30-apr-98.pdf 
(Untested)
                                            

                                

                                    
http://www.wapforum.org/what/technical_1_1.htmWAP 1.1 
                                    

                                                WBXML 1.1 - SPEC-WBXML-19990616.pdf 
(Tested)
                                            

                                                WML 1.1 - SPEC-WML-19990616.pdf 
(Untested)
                                            

                                                CHANNEL 1.1 - SPEC-WTA-19990716.pdf 
(Untested)
                                            
                                    
                                

                                    
http://www.wapforum.org/what/technical_1_2.htmWAP 1.2 
                                    

                                                WBXML 1.2 - SPEC-WBXML-19991104.pdf 
(Tested)
                                            

                                                WML 1.2 - SPEC-WML-19991104.pdf 
(Untested)
                                            

                                                SI 1.0 - WAP-167-ServiceInd-20010731-a.pdf 
(Tested)
                                            

                                                SL 1.0 - WAP-168-ServiceLoad-20010731-a.pdf 
(Tested)
                                            
                                      
                                

                                    
http://www.wapforum.org/what/technical_1_2_1.htmWAP 1.2.1 
                                    

                                                WBXML 1.3 - WAP-192-WBXML-20010725-a.pdf 
(Tested)
                                            

                                                WML 1.3 - WAP-191-WML-20000219-a.pdf 
(Untested)
                                            

                                                CO 1.0 - WAP-175-CacheOp-20010731-a.pdf 
(Untested)
                                            
                                     
                                

                                    
http://www.wapforum.org/what/technical.htmWAP 2.0 
                                    

                                                Prov 1.0 - WAP-183-PROVCONT-20010724-a.pdf 
(Tested)
                                            

                                                WTA WML 1.2 - WAP-266-WTA-20010908-a.pdf 
(Untested)
                                            

                                                CHANNEL 1.2 - WAP-266-WTA-20010908-a.pdf 
(Untested)
                                            
                                     
                                

                    

                        
http://www.openmobilealliance.org/OMA  Specifications
                        

                                    EMail Notification 1.0
                                    

                                                EMN 1.0 - OMA-ERELD-EMN-V1_0-20021031-C.pdf 
(Tested)
                                            
                              
                                

                                    Rights Expression Language Version 1.0
                                    

                                                DRMREL 1.0 - OMA-Download-DRMREL-v1_0-20020913-a.pdf 
(Untested)
                                            
                                      
                                
                        
                    

                        Nokia / Ericsson
                        

                                    OTA Settings
                                    

                                                OTA_settings_general_7_0.pdf 
(Tested)
                                            
                                      
                                
                         
                    
                    
                        
http://www.openmobilealliance.org/syncml/SyncML  Spcifications
                        

                                    SYNCML 1.1.1 
                                    

                                                syncml_represent_v111_20021002.pdf 
(Untested)
                                            

                                                syncml_metinf_v111_20021002.pdf 
(Untested)
                                            

                                                syncml_devinf_v111_20021002.pdf 
(Untested)
                                            
                                      
                                
                         
                    

                       
http://www.openmobilealliance.org/wirelessvillage/Wireless-Village  Spcifications
                        

                                    WV CSP 1.1
                                    

                                                WSP 1.1 - WV_CSP_WBXML_v1.1.pdf 
(Untested)
                                            
                                      
                                
                         
                    

        
1.3.Project

            The WBXML Library project is hosted on 
http://sourceforge.net/projects/wbxmllib/SourceForge 
        

            The latests package can be downloaded: 
http://sourceforge.net/project/showfiles.php?group_id=55834&release_id=126876here 
        

            CVS Access: :ext:anonymous@cvs.wbxmllib.sourceforge.net:/cvsroot/wbxmllib            
        

            
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/wbxmllibBrowe the sources Online 
        
1.4.Code Documentation

            The Code Documentation, generated by 
http://www.doxygen.org/doxygen  is http://wbxmllib.sourceforge.net/html/index.htmlHERE  !
        
Chapter2.Building and Installing
Table of Contents
2.1. #d3e198Linux 2.2. #d3e224Windows 2.1.Linux

            You must have the 
http://expat.sourceforge.net/Expat  library installed.
        
This is what you must do to install the WBXML Library on Linux

                    
$ ./bootstrap
                

                    
$ make all
                

                    
$ make install
                

                    
$ make clean
                
Procedure2.1.Linux Install
[Warning] Warning 
                You may have to chmod 'bootstrap' file to 755, if not already done.
            

            To make the library verbose, use the '-DWBXML_LIB_VERBOSE' CFLAG in src/Makefile.am
        
2.2.Windows

            The 
http://expat.sourceforge.net/Expat  binary is provided in "/win32/expat".
        

            Just open the 'win32/libwbxml.dsw' VC++ workspace, and build:
            

                        libwbxml2.dll - The main library
                    

                        libwbxml2_conv.dll - The WBXML <=> XML convertion library
                    

                        xml2wbxml.exe - The XML to WBXML convertion tool
                    

                        xml2wbxml.exe - The WBXML to XML convertion tool
                    

        

            To make the library verbose, define the 'WBXML_LIB_VERBOSE' Macro in 'src/wbxml_log.h'
        
Chapter3.Using WBXML Library
Table of Contents
3.1. #d3e246File convertion Tools (xml2wbxml, wbxml2xml) 3.2. #d3e254Buffer convertion Library (libwbxml2_conv) 3.3. #d3e262Low level WBXML Parser and Encoder (libwbxml2) 
        There are three ways of using the WBXML Library:
        

                File convertion Tools : The xml2wbxml and wbxml2xml programs.
            

                Buffer convertion Library : The libwbxml2_conv library.
            

                Low level WBXML Parser and Encoder : The libwbxml2 library.
            

    
3.1.File convertion Tools (xml2wbxml, wbxml2xml)

            This are the high level components of the WBXML Library. This tools need the libwbxml2_conv, libwbxml2 and 
http://expat.sourceforge.net/Expat  libraries.
        

            There are two Convertion Tools:
            

                    xml2wbxml tool - Convert an XML File to a WBXML File.
                

                    wbxml2xml tool - Convert a WBXML File to an XML File.
                

        
3.2.Buffer convertion Library (libwbxml2_conv)

            This is the library version of the Convertion Tools. Use this library if you need to convert 
            XML and WBXML buffers inside your own Program. This library needs to link with the libwbxml2 and 
http://expat.sourceforge.net/Expat  libraries.
        

            There are two Convertion Functions:
            

                    xml2wbxml function - Convert an XML Buffer to a WBXML Buffer.
                

                    wbxml2xml function - Convert a WBXML Buffer to an XML Buffer.
                

        
3.3.Low level WBXML Parser and Encoder (libwbxml2)

            This is the low-level WBXML Library component. It uses an intermediary WBXMLTree structure to represent a WBXML Document,
            and it contains a WBXML Parser and a WBXML Encoder. Use this library if you have to deal with an in-memory representation
            of the WBXML Document, or if you want to parse a WBXML Document into your own internal structures. This is a standalone library.
        

            The main modules of the libwbxml2 library:
            
wbxml_buffers
                            This contains functions to manipulate generic Buffers (WBXMLBuffer). This buffers are used in the 'wbxml_elt' module
                            to store Literal Tags and Literal Attribute Names.
                        
wbxml_tables
                            This module contains all the WBXML Tables. It defines too the structures:
                            

                                    WBXMLTagEntry - A WBXML Tag Entry in WBXML Language Table
                                

                                    WBXMLAttrEntry - A WBXML Attribute Entry in WBXML Language Table
                                

                                    WBXMLLangEntry - A full WBXML Language Table
                                

                        
wbxml_elt
                            This module defines the WBXML Elements used in the WBXML Tree structure:
                            

                                    WBXMLTag - A WBXML Tag
                                

                                    WBXMLAttributeName - A WBXML Attribute Name
                                

                                    WBXMLAttribute - A WBXML Attribute
                                

                        

                            

        typedef struct WBXMLTag_s {
            WBXMLValueType type;                    /* Tag Type (Token or Literal) */
            union {
                const WBXMLTagEntry   *token;       /* Token Tag (MUST be const structure, ie from wbxml_tables.c) */
                WBXMLBuffer           *literal;     /* Literal Tag (MUST be dynamically allocated WBXMLBuffer) */
            } u;
        } WBXMLTag;
                            

                            The WBXMLTag type can be either:
                            

                                    WBXML_VALUE_TOKEN - In this case, the Tag Name is a token, a pointer to a WBXMLTagEntry structure.
                                

                                    WBXML_VALUE_LITERAL - In this case, the Tag Name is a literal, a pointer to a WBXMLBuffer structure.
                                

                        

                            

        typedef struct WBXMLAttributeName_s {
            WBXMLValueType  type;               /* Attribute Name Type (Token or Literal) */
            union {
                const WBXMLAttrEntry *token;    /* Token Attribute Name (MUST be const structure, ie from wbxml_tables.c) */
                WBXMLBuffer          *literal;  /* Literal Attribute Name (MUST be dynamically allocated WBXMLBuffer) */
            } u;
        } WBXMLAttributeName;
                            
                        
                            The WBXMLAttributeName type can be either:
                            

                                    WBXML_VALUE_TOKEN - In this case, the Attribute Name is a token, a pointer to a WBXMLAttrEntry structure.
                                

                                    WBXML_VALUE_LITERAL - In this case, the Tag Name is a literal, a pointer to a WBXMLBuffer structure.
                                

                        

                            

        typedef struct WBXMLAttribute_s {
            WBXMLAttributeName  *name;  /* Attribute Name */
            WBXMLBuffer *value;         /* Full Attribute Value */
        } WBXMLAttribute;
                            
                         
                            The WBXMLAttribute contains:
                            

                                    An Attribute Name : A WBXMLAttributeName structure.
                                

                                    An Attribute Value : A WBXMLBuffer structure.
                                

                        
[Warning] Warning 
                                

The'value'partofanWBXMLAttributecontaintheFULLattributevalue.

Forexample,withtheattribute:url="http://127.0.0.1/"

ifthe'name'partisthis:

-name->u.token->wbxmlCodePage:0x00

-name->u.token->wbxmlToken:0x4b

-name->u.token->xmlName:"url"

-name->u.token->xmlValue:"http://"


then,'value'isstill:"http://127.0.0.1/"


Ofcourse(inthisexample)itshouldbebettertohavethewbxmlToken0x4a("url"/NULL).Soyoumustn'ttakeinto

accountthe'xmlValue'fieldfor'name'togettheAttributeValueofthisAttribute.


                            
wbxml_tree
                            This module define a WBXML Tree. This is the main in-memory representation of a WBXML Document, used by
                            the WBXML Parser and the WBXML Encoder.
                        

                            A WBXML Tree is composed of WBXML Nodes which can be: an Element Node, a Text Node or a PI Node.
                            

        typedef enum WBXMLTreeNodeType_e
        {
            WBXML_TREE_ELEMENT_NODE = 0, /* Element Node */
            WBXML_TREE_TEXT_NODE,        /* Text Node */
            WBXML_TREE_PI_NODE,          /* PI Node */
        } WBXMLTreeNodeType;
                            

                        

                            A WBXMLTreeAttribute is a structure that permits to chain several WBXMLAttribute structures into a List.
                            

        typedef struct WBXMLTreeAttribute_s
        {
            WBXMLAttribute  *attr;              /* Attribute */
            struct WBXMLTreeAttribute_s  *next; /* Next attribute */
        } WBXMLTreeAttribute;
                            

                        

                             A WBXML Tree is composed of WBXML Nodes.
                            

        typedef struct WBXMLTreeNode_s
        {
            WBXMLTreeNodeType   type;       /* Node Type */
            WBXMLTag            *name;      /* Node Name (if type is 'WBXML_TREE_ELEMENT_NODE') */
            WBXMLTreeAttribute  *attrs;     /* Node Attributes (if type is 'WBXML_TREE_ELEMENT_NODE') */
            WBXMLBuffer         *content;   /* Node Content (if  type is 'WBXML_TREE_TEXT_NODE')  */
                
            struct WBXMLTreeNode_s  *parent;    /* Parent Node */
            struct WBXMLTreeNode_s  *children;  /* Children Node */
            struct WBXMLTreeNode_s  *next;      /* Next sibling Node */
            struct WBXMLTreeNode_s  *prev;      /* Previous sibling Node */
        } WBXMLTreeNode;
                            

                        

                            Finally, a WBXML Tree defines a WBXM Language and a root WBXML Node.
                            

        typedef struct WBXMLTree_s
        {    
            const WBXMLLangEntry  *lang; /* Language Table */
            WBXMLTreeNode   *root;       /* Root Element */
        } WBXMLTree;
                            
                             
                        
wbxml_encoder
                            The WBXML Encoder is used to encode a WBXML Tree into:
                            

                                    A WBXML Document : wbxml_encoder_encode_to_wbxml()
                                

                                    An XML Document : wbxml_encoder_encode_to_xml()
                                

                            Cf. the Reference Chapter for more informations about this functions.
                        
wbxml_parser
                            The WBXML Parser can be used in two ways:
                            

                                    Parse a WBXML Document into a WBXML Tree : wbxml_parser_parse_to_tree()
                                

                                    Parse a WBXML Document into your own internal structures, by implementing your own Parser Callbacks : wbxml_parser_parse()
                                
  
                            Cf. the Reference Chapter for more informations about this functions.                          
                        
                
        
Chapter4.Reference
Table of Contents
4.1. #d3e333libwbxml2 4.1.1. #d3e335WBXML Encoder 4.1.1.1. #d3e337Encoder Creation 4.1.1.2. #d3e365Encoder Initialization when generating WBXML or XML 4.1.1.3. #d3e394Encoder Initialization when generating WBXML 4.1.1.4. #d3e410Encoder Initialization when generating XML 4.1.1.5. #d3e444Encoding Functions 4.1.1.6. #d3e485Example 4.1.2. #d3e490WBXML Parser 4.1.2.1. #d3e496Parse to WBXML Tree 4.1.2.2. #d3e513Parse with User Defined Callbacks 4.1.3. #d3e765WBXML Tree 4.2. #d3e768libwbxml2_conv 4.2.1. #d3e771XML to WBXML Convertion 4.2.1.1. #d3e773Prototype 4.2.1.2. #d3e788XML2WBXMLParameters Structure 4.2.1.3. #d3e792Example 4.2.2. #d3e797WBXML to XML Convertion 4.2.2.1. #d3e799Prototype 4.2.2.2. #d3e814WBXML2XMLParameters Structure 4.2.2.3. #d3e818Example 4.3. #d3e823Tools 4.3.1. #d3e826xml2wbxml 4.3.2. #d3e843wbxml2xml 4.1.libwbxml2
Table of Contents
4.1.1. #d3e335WBXML Encoder 4.1.1.1. #d3e337Encoder Creation 4.1.1.2. #d3e365Encoder Initialization when generating WBXML or XML 4.1.1.3. #d3e394Encoder Initialization when generating WBXML 4.1.1.4. #d3e410Encoder Initialization when generating XML 4.1.1.5. #d3e444Encoding Functions 4.1.1.6. #d3e485Example 4.1.2. #d3e490WBXML Parser 4.1.2.1. #d3e496Parse to WBXML Tree 4.1.2.2. #d3e513Parse with User Defined Callbacks 4.1.3. #d3e765WBXML Tree 4.1.1.WBXML Encoder
Table of Contents
4.1.1.1. #d3e337Encoder Creation 4.1.1.2. #d3e365Encoder Initialization when generating WBXML or XML 4.1.1.3. #d3e394Encoder Initialization when generating WBXML 4.1.1.4. #d3e410Encoder Initialization when generating XML 4.1.1.5. #d3e444Encoding Functions 4.1.1.6. #d3e485Example 4.1.1.1.Encoder Creation

                    This two functions permit to create and destroy WBXML Encoder instances.
                
4.1.1.1.1.wbxml_encoder_create
#include <wbxml.h>WBXMLEncoder *wbxml_encoder_create();void;

                        Create a WBXML Encoder instance. Returns NULL if not enough memory.
                    
4.1.1.1.2.wbxml_encoder_destroy
#include <wbxml.h>void wbxml_encoder_destroy(encoder);WBXMLEncoder *encoder;

                        Destroy a WBXML Encoder instance. This function doesn't destroy the WBXMLTree associated with that WBXML Encoder.
                    
4.1.1.1.3.Example

                        
Example4.1.WBXML Encoder Creation/Destruction

        #include <wbxml.h>
        ...
        
        WBXMLEncoder *wbxml_encoder = NULL;
        
        /* Create Encoder */
        if ((wbxml_encoder = wbxml_encoder_create()) == NULL)
            return 0;
        
        ...
        << Your Code Here >>
        ...
        
        /* Destroy Encoder */
        wbxml_encoder_destroy(wbxml_encoder);
                            

                    
4.1.1.2.Encoder Initialization when generating WBXML or XML

                    This functions that initialize the WBXML Encoder are usefull when generating WBXML and XML.
                
4.1.1.2.1.wbxml_encoder_set_ignore_empty_text
#include <wbxml.h>void wbxml_encoder_set_ignore_empty_text(encoder, set_ignore);WBXMLEncoder *encoder;WB_BOOL set_ignore;

                        Set the WBXML Encoder to ignore empty texts (ie: ignorable Whitespaces) when generating output 
[Default: TRUE].
                    
4.1.1.2.2.wbxml_encoder_set_remove_text_blanks
#include <wbxml.h>void wbxml_encoder_set_remove_text_blanks(encoder, set_remove);WBXMLEncoder *encoder;WB_BOOL set_remove;

                        Set the WBXML Encoder to remove leading and trailing blanks in texts (ie: ignorable Whitespaces) when generating output 
[Default: TRUE].
                    
4.1.1.3.Encoder Initialization when generating WBXML

                    This functions that initialize the WBXML Encoder are only usefull when generating WBXML.
                
4.1.1.3.1.wbxml_encoder_set_use_strtbl
#include <wbxml.h>void wbxml_encoder_set_use_strtbl(encoder, use_strtbl);WBXMLEncoder *encoder;WB_BOOL use_strtbl;

                        Set if we use String Table when Encoding into WBXML 
[Default: TRUE].
                    
4.1.1.4.Encoder Initialization when generating XML

                    This functions that initialize the WBXML Encoder are only usefull when generating XML.
                
4.1.1.4.1.wbxml_encoder_set_xml_gen_type
#include <wbxml.h>void wbxml_encoder_set_xml_gen_type(encoder, gen_type);WBXMLEncoder *encoder;WBXMLEncoderXMLGenType gen_type;

                        Set the WBXML Encoder XML Generation Type, when generating XML 
[Default: WBXML_ENCODER_XML_GEN_COMPACT].
                    

                        Generation Mode:
                        

                                WBXML_ENCODER_XML_GEN_COMPACT - Compact XML generation
                            

                                WBXML_ENCODER_XML_GEN_INDENT - Indented XML generation
                            

                                WBXML_ENCODER_XML_GEN_CANONICAL - Canonical XML generation
                            

                    
4.1.1.4.2.wbxml_encoder_set_indent
#include <wbxml.h>void wbxml_encoder_set_indent(encoder, indent);WBXMLEncoder *encoder;WB_UTINY indent;

                        Set the WBXML Encoder indent, when generating XML in WBXML_ENCODER_XML_GEN_INDENT mode 
[Default: 0].
                    
4.1.1.5.Encoding Functions

                    This are the main functions to encode a WBXMLTree.
                
4.1.1.5.1.wbxml_encoder_set_tree
#include <wbxml.h>void wbxml_encoder_set_tree(encoder, tree);WBXMLEncoder *encoder;WBXMLTree *tree;

                        Set the WBXML Tree to encode. You MUST call this function before calling following wbxml_encoder_encode_to_wbxml() or wbxml_encoder_encode_to_xml() function.
                    
4.1.1.5.2.wbxml_encoder_encode_to_wbxml
#include <wbxml.h>WBXMLError wbxml_encoder_encode_to_wbxml(encoder, wbxml, wbxml_len);WBXMLEncoder *encoder;WB_UTINY **wbxml;WB_ULONG *wbxml_len;

                        Encode a WBXML Tree to WBXML. wbxml_encoder_set_tree() MUST be used before calling this function.
                    
4.1.1.5.3.wbxml_encoder_encode_to_xml
#include <wbxml.h>WBXMLError wbxml_encoder_encode_to_xml(encoder, xml);WBXMLEncoder *encoder;WB_UTINY **xml;

                        Encode a WBXML Tree to XML. wbxml_encoder_set_tree() MUST be used before calling this function.
                    
4.1.1.6.Example
Example4.2.WBXML Encoder Use

        #include <wbxml.h>
        ...
                            
        WBXMLEncoder *wbxml_encoder = NULL;
        WBXMLTree *tree = NULL;
        WB_UTINY *wbxml = NULL;
        WB_ULONG wbxml_len = 0;
        
        ...
        << tree created and filled >>
        ...
        
        /* Create WBXML Encoder */
        if ((wbxml_encoder = wbxml_encoder_create()) == NULL) {
            wbxml_tree_destroy(tree);
            return WBXML_ERROR_NOT_ENOUGH_MEMORY;
        }
        
        /* Set the WBXML Tree to encode */
        wbxml_encoder_set_tree(wbxml_encoder, tree);
                      
        /* Ignores "Empty Text" Nodes */
        wbxml_encoder_set_ignore_empty_text(wbxml_encoder, TRUE);
    
        /* Remove leading and trailing whitespaces in "Text Nodes" */
        wbxml_encoder_set_remove_text_blanks(wbxml_encoder, TRUE);
    
        /* Use String Table */
        wbxml_encoder_set_use_strtbl(wbxml_encoder, TRUE);
    
        /* Encode to WBXML */
        ret = wbxml_encoder_encode_to_wbxml(wbxml_encoder, &wbxml, &wbxml_len);
    
        /* Clean-up */
        wbxml_tree_destroy(tree);
        wbxml_encoder_destroy(wbxml_encoder);
        
        if (ret != WBXML_OK) {
            printf("Encoding failed: %s\n", wbxml_errors_string(ret));
        }
        else {
            printf("Encoding succeded\n");
            
            ...
            << Do what you have to do with this WBXML Buffer >>
            ...
            
            wbxml_free(wbxml);
        }
                    
4.1.2.WBXML Parser
Table of Contents
4.1.2.1. #d3e496Parse to WBXML Tree 4.1.2.2. #d3e513Parse with User Defined Callbacks 
                There are two ways of using the WBXML Parser
                

                        Parse a WBXML Document into a WBXML Tree : wbxml_parser_parse_to_tree()
                    

                        Parse a WBXML Document into your own internal structures, by implementing your own Parser Callbacks : wbxml_parser_parse()
                    

            
4.1.2.1.Parse to WBXML Tree

                    This is the easier method. You just have one function to call, and the WBXML Document is converted
                    to an in-memory representation: the WBXML Tree.
                
4.1.2.1.1.wbxml_parser_parse_to_tree
#include <wbxml.h>WBXMLError wbxml_parser_parse_to_tree(wbxml, wbxml_len, tree);WB_UTINY *wbxml;WB_ULONG wbxml_len;WBXMLTree  **tree;

                       Parse a WBXML Document and creates the associated WBXML Tree. Returns WBXML_OK if no error, an error code otherwise.
                    
4.1.2.2.Parse with User Defined Callbacks
4.1.2.2.1.Parser Creation

                        This two functions permit to create and destroy WBXML Parser instances.
                    
4.1.2.2.1.1.wbxml_parser_create
#include <wbxml.h>WBXMLParser *wbxml_parser_create();void;

                            Create a WBXML Parser instance. Returns NULL if not enough memory.
                        
4.1.2.2.1.2.wbxml_parser_destroy
#include <wbxml.h>void wbxml_parser_destroy(parser);WBXMLParser *parser;

                            Destroy a WBXML Parser instance. The User Data is not destroyed by this function.
                        
4.1.2.2.1.3.Example

                            
Example4.3.WBXML Parser Creation/Destruction

        #include <wbxml.h>
        ...
        
        WBXMLParser *wbxml_parser = NULL;
        
        /* Create Parser */
        if ((wbxml_parser = wbxml_parser_create()) == NULL)
            return 0;
        
        ...
        << Your Code Here >>
        ...
        
        /* Destroy Parser */
        wbxml_parser_destroy(wbxml_parser);
                                

                        
4.1.2.2.2.Parser Initialisation

                        This functions are used to initialise the Parser.
                    
4.1.2.2.2.1.wbxml_parser_set_user_data
#include <wbxml.h>void wbxml_parser_set_user_data(parser, user_data);WBXMLParser *parser;void *user_data;

                            Set a pointer to User Data. This User Data is passed back to the user in User Defined Callbacks
                            while parsing the WBXML document.
                        
4.1.2.2.2.2.wbxml_parser_set_content_handler
#include <wbxml.h>void wbxml_parser_set_content_handler(parser, content_handler);WBXMLParser *parser;WBXMLContentHandler *content_handler;

                            Set the User Defined Callbacks to use while parsing the WBXML document.
                        
4.1.2.2.2.3.Parser Content Handler

                            A WBXMLContentHandler is a structure that defines all the Callback Functions.
                            

        typedef struct WBXMLContentHandler_s {
            WBXMLStartDocumentHandler start_document_clb;       /* Start Document Handler */
            WBXMLEndDocumentHandler end_document_clb;           /* End Document handler */
            WBXMLStartElementHandler start_element_clb;         /* Start Element handler */
            WBXMLEndElementHandler end_element_clb;             /* End Element handler */
            WBXMLCharactersHandler characters_clb;              /* Characters handler */
            WBXMLProcessingInstructionHandler pi_clb;           /* Processing Instruction Handler */
        } WBXMLContentHandler;
                            

                        

                                    
void WBXMLStartDocumentHandler(ctx, charset, lang);void *ctx;WB_LONGcharset;const WBXMLLangEntry *lang;

                                    
                                    

                                        This Callback function is called when starting to parse the WBXML document.
                                        

                                                ctx: The User Data
                                            

                                                charset: IANA Charset MIBenum of the WBXML document
                                            

                                                lang: WBXML Language Table (defined in wbxml_tables.[h|c])
                                            

                                    

                                

                                    
void WBXMLEndDocumentHandler(ctx);void *ctx;

                                    
                                    

                                        This Callback function is called when finished to parse the WBXML document. The 
                                        parameter is the User Data.
                                    

                                

                                    
void WBXMLStartElementHandler(ctx, localName, atts, empty);void *ctx;WBXMLTag *localName;WBXMLAttribute **atts;WB_BOOLempty;

                                    
                                    

                                        This Callback function is called when parsing a WBXML start Element.
                                        

                                                ctx: The User Data
                                            

                                                localName: The WBXML Tag
                                            

                                                atts: The WBXML Attribute list
                                            

                                                empty: TRUE if this is an empty Element, FALSE otherwise
                                            

                                    

                                

                                    
void WBXMLEndElementHandler(ctx, localName, empty);void *ctx;WBXMLTag *localName;WB_BOOLempty;

                                    
                                    

                                        This Callback function is called when parsing a WBXML end Element.
                                        

                                                ctx: The User Data
                                            

                                                localName: The WBXML Tag
                                            

                                                empty: TRUE if this is an empty Element, FALSE otherwise
                                            

                                    

                                

                                    
void WBXMLCharactersHandler(ctx, ch, start, length);void *ctx;WB_UTINY *ch;WB_ULONGstart;WB_ULONGlength;

                                    
                                    

                                        This Callback function is called when parsing a Content Data.
                                        

                                                ctx: The User Data
                                            

                                                ch: Buffer of character data
                                            

                                                start: Starting index in Buffer
                                            

                                                length: Length of data
                                            

                                    

                                

                                    
void WBXMLProcessingInstructionHandler(ctx, target, data);void *ctx;const WB_UTINY *target;WB_UTINY *data;

                                    
                                    

                                        This Callback function is called when parsing a Processing Instruction.
                                        

                                                ctx: The User Data
                                            

                                                target: The processing instruction target
                                            

                                                data: The processing instruction data
                                            

                                    

                                
4.1.2.2.2.4.wbxml_parser_set_main_table
#include <wbxml.h>void wbxml_parser_set_main_table(parser, main_table);WBXMLParser *parser;const WBXMLLangEntry *main_table;

                            Set the main WBXML Languages Table. You should not call this function unless you
                            know what you are doing (the main table of wbxml_tables.c is already set when
                            creating the WBXML Parser).
                        
4.1.2.2.2.5.wbxml_parser_set_wbxml_public_id
#include <wbxml.h>WB_BOOL wbxml_parser_set_wbxml_public_id(parser, public_id);WBXMLParser *parser;WB_LONG public_id;

                            Force to parse the Document with a given WBXML Public ID. Must be called BEFORE parsing of document.
                        
4.1.2.2.3.Parser Informations

                        This functions are used to retrieve informations while or after Parsing.
                    
4.1.2.2.3.1.wbxml_parser_get_wbxml_public_id
#include <wbxml.h>WB_ULONG wbxml_parser_get_wbxml_public_id(parser);WBXMLParser *parser;

                            Get the WBXML Public ID of current parsing WBXML document.
                        
4.1.2.2.3.2.wbxml_parser_get_xml_public_id
#include <wbxml.h>const WB_UTINY *wbxml_parser_get_xml_public_id(parser);WBXMLParser *parser;

                            Get the XML Public ID of current parsing WBXML document.
                        
4.1.2.2.3.3.wbxml_parser_get_wbxml_version
#include <wbxml.h>WB_UTINY wbxml_parser_get_wbxml_version(parser);WBXMLParser *parser;

                            Get the WBXML Version of current parsing WBXML document.
                        
4.1.2.2.3.4.wbxml_parser_get_current_byte_index
#include <wbxml.h>WB_LONG wbxml_parser_get_current_byte_index(parser);WBXMLParser *parser;

                            Get current parsing position in WBXML document.
                        
4.1.2.2.4.Parsing function
#include <wbxml.h>WBXMLError wbxml_parser_parse(parser, wbxml, wbxml_len);WBXMLParser *parser;WB_UTINY *wbxml;WB_ULONG wbxml_len;

                        This function actually launch the Parsing of the WBXML Document.
                        

                                parser: The Parser to use
                            

                                wbxml: The WBXML Document to parser
                            

                                wbxml_len: The WBXML Document length
                            

                    
4.1.2.2.5.Example
Example4.4.WBXML Parser use

        #include <string.h>
        #include <wbxml.h>
        
        #define INPUT_BUFFER_SIZE 1000
        
        
        /** Start Document Callback */
        void parse_clb_start_document(void *ctx, WB_LONG charset, const WBXMLLangEntry *lang)
        {
            printf("Parsing Document:\n"
                   "\tRoot Element: %s\n"
                   "\tPublic ID: %s\n"
                   "\tDTD: %s\n",
                   lang->publicID->xmlRootElt,
                   lang->publicID->xmlPublicID,
                   lang->publicID->xmlDTD);
        }
        
        /** End Document Callback */
        void parse_clb_end_document(void *ctx)
        {
            printf("End of Document\n");
        }
        
        /** Start Element Callback */
        void parse_clb_start_element(void *ctx, WBXMLTag *element, WBXMLAttribute **atts, WB_BOOL empty)
        {    
            WB_ULONG *indent = (WB_ULONG *) ctx;
            
            WB_ULONG i = 0, j = 0;
            
            /* Indent start Element */
            for (i=0; i<*indent; i++)
                printf(" ");
        
            /* Write start Element */
            printf("<%s", wbxml_tag_get_xml_name(element));
            
            /* Write Attributes */
            if (atts != NULL) {
                while (atts[j] != NULL)
                {
                    /* Write Attribute Name */
                    printf(" %s=\"%s\"", wbxml_attribute_get_xml_name(atts[j]), wbxml_attribute_get_xml_value(atts[j]));  
                    j++;
                }        
            }
            
            /* End of start Element */
            if (empty) {
                printf("/>\n");
            }
            else {
                printf(">\n");
                (*indent)++;
            }
        }
        
        /** End Element Callback */
        void parse_clb_end_element(void *ctx, WBXMLTag *element, WB_BOOL empty)
        {
            WB_ULONG *indent = (WB_ULONG *) ctx;
            WB_ULONG i = 0;
        
            if (!empty) {
                (*indent)--;
        
                /* Indent End Element */
                for (i=0; i<*indent; i++)
                    printf(" ");
                    
                /* Write end tag */
                printf("</%s>\n", wbxml_tag_get_xml_name(element));        
            }
        }
        
        /** Characters Callback */
        void parse_clb_characters(void *ctx, WB_UTINY *ch, WB_ULONG start, WB_ULONG length)
        {
            WB_ULONG *indent = (WB_ULONG *) ctx;
            WB_ULONG i = 0;
            
            /* Indent Characters */
            for (i=0; i<*indent; i++)
                printf(" ");
        
            /* Write Content */
            for(i=start; i<length; i++)
                printf("%c", ch[i]);
        
            printf("\n");
        }
        
        /** Main Function */
        WB_LONG main(WB_LONG argc, WB_TINY **argv) 
        {
            FILE *input_file = NULL;
            WB_ULONG count = 0, total = 0, wbxml_len = 0;
            WB_UTINY input_buffer[INPUT_BUFFER_SIZE + 1];
        
            WBXMLParser *wbxml_parser = NULL;
            WB_UTINY *wbxml = NULL;
            WB_ULONG indent = 0, error_index = 0;
            WBXMLError ret = WBXML_OK;
            WBXMLContentHandler parse_handler = 
                {
                    parse_clb_start_document,
                    parse_clb_end_document,
                    parse_clb_start_element,
                    parse_clb_end_element,
                    parse_clb_characters,
                    NULL
                };
                
            if (argc != 2) {
                printf("Missing argument: WBXML Filename");
                return 0;
            }
        
            /**********************************
             *  Read the WBXML Document
             */
        
            /* Open WBXML document */
            if ((input_file = fopen(argv[1], "rb")) == NULL) {
                printf("Failed to open %s\n", argv[1]);
                return 0;
            }
        
            /* Read WBXML document */
            while(!feof(input_file))    {
                count = fread(input_buffer, sizeof(WB_UTINY), INPUT_BUFFER_SIZE, input_file);
                if (ferror(input_file))      {
                    printf("Error while reading from file %s\n", argv[1]);
                    fclose(input_file);
                    if (wbxml != NULL)
                        wbxml_free(wbxml);
                    return 0;
                }
        
                total += count;
                if ((wbxml = wbxml_realloc(wbxml, total)) == NULL) {
                    printf("Not enought memory\n");
                    fclose(input_file);
                    if (wbxml != NULL)
                        wbxml_free(wbxml);
                    return 0;
                }
        
                memcpy(wbxml + wbxml_len, input_buffer, count);
                wbxml_len += count;
            }
        
            fclose(input_file);
            
            /* Create WBXML Parser */
            if ((wbxml_parser = wbxml_parser_create()) == NULL) {
                wbxml_free(wbxml);
                return 0;
            }
            
            /* Initialize WBXML Parser */
            wbxml_parser_set_user_data(wbxml_parser, &indent);
            wbxml_parser_set_content_handler(wbxml_parser, &parse_handler);
            
            /* Parse WBXML document */
            if ((ret = wbxml_parser_parse(wbxml_parser, wbxml, wbxml_len)) != WBXML_OK)
            {
                error_index = wbxml_parser_get_current_byte_index(wbxml_parser);
                printf("Parsing failed at %u - Token %x - %s", error_index, wbxml[error_index], wbxml_errors_string(ret));
            }
            else {
                printf("Parsing OK !");          
            }
            
            /* Destroy WBXML Parser */
            wbxml_parser_destroy(wbxml_parser);
        
            /* Free wbxml buffer */
            wbxml_free(wbxml);
        
            return 0;
        }
                        
4.1.3.WBXML Tree

                TODO !!!
            
4.2.libwbxml2_conv
Table of Contents
4.2.1. #d3e771XML to WBXML Convertion 4.2.1.1. #d3e773Prototype 4.2.1.2. #d3e788XML2WBXMLParameters Structure 4.2.1.3. #d3e792Example 4.2.2. #d3e797WBXML to XML Convertion 4.2.2.1. #d3e799Prototype 4.2.2.2. #d3e814WBXML2XMLParameters Structure 4.2.2.3. #d3e818Example 
            This functions permit to convert directly XML to WBXML, and WBXML to XML.
        
4.2.1.XML to WBXML Convertion
Table of Contents
4.2.1.1. #d3e773Prototype 4.2.1.2. #d3e788XML2WBXMLParameters Structure 4.2.1.3. #d3e792Example 4.2.1.1.Prototype
#include <wbxml_conv.h>WBXMLError xml2wbxml(xml, wbxml, wbxml_len, params);WB_UTINY *xml;WB_UTINY **wbxml;WB_ULONG *wbxml_len;XML2WBXMLParameters *params;
4.2.1.2.XML2WBXMLParameters Structure

                    XML2WBXMLParameters Structure:
                    

        typedef struct XML2WBXMLParameters_s {
            WB_BOOL keep_ignorable_ws;  /* Keep Ignorable Whitespaces (Default: FALSE) */
            WB_BOOL use_strtbl;         /* Generate String Table (Default: TRUE) */
        } XML2WBXMLParameters;
                    

                
4.2.1.3.Example
Example4.5.XML to WBXML Convertion

        #include <wbxml_conv.h>
        
        ...
        
        WB_UTINY *wbxml = NULL, *xml = NULL;
        WB_LONG wbxml_len = 0;
        WBXMLError ret = WBXML_OK;
        XML2WBXMLParameters params;
        
        ...
        << Fill the 'xml' buffer with the XML Document to convert >>
        ...
        
        /* Converter parameters */
        params.use_strtbl = TRUE;
        params.keep_ignorable_ws = FALSE;                    
        
        /* Convert XML document */
        ret = xml2wbxml(xml, &wbxml, &wbxml_len, &params);
        if (ret != WBXML_OK) {
            printf("xml2wbxml failed: %s\n", wbxml_errors_string(ret));
        }
        else {
            printf("xml2wbxml succeded\n");
            
            ...
            << Do what you have to do with this WBXML Buffer >>
            ...
            
            /* Clean-up */
            wbxml_free(wbxml);
        }
        
        ...
                    
4.2.2.WBXML to XML Convertion
Table of Contents
4.2.2.1. #d3e799Prototype 4.2.2.2. #d3e814WBXML2XMLParameters Structure 4.2.2.3. #d3e818Example 4.2.2.1.Prototype
#include <wbxml_conv.h>WBXMLError wbxml2xml(wbxml, wbxml_len, xml, params);WB_UTINY *wbxml;WB_ULONG wbxml_len;WB_UTINY **xml;WBXML2XMLParameters *params;
4.2.2.2.WBXML2XMLParameters Structure

                    

        typedef struct WBXML2XMLParameters_s {
            WBXMLEncoderXMLGenType gen_type;    /* WBXML_ENCODER_XML_GEN_COMPACT | WBXML_ENCODER_XML_GEN_INDENT | WBXML_ENCODER_XML_GEN_CANONICAL (Default: WBXML_ENCODER_XML_GEN_INDENT) */
            WB_UTINY indent;                    /* Indentation Delta, when using WBXML_ENCODER_XML_GEN_INDENT Generation Type (Default: 0) */
            WB_BOOL keep_ignorable_ws;          /* Keep Ignorable Whitespaces (Default: FALSE) */
        } WBXML2XMLParameters;
                    

                
4.2.2.3.Example
Example4.6.WBXML to XML Convertion

        #include <wbxml_conv.h>
        
        ...
                            
        WB_UTINY *wbxml = NULL, *xml = NULL;
        WB_LONG wbxml_size = 0;
        WBXMLError ret = WBXML_OK;
        WBXML2XMLParameters params;
        
        ...
        << Fill the 'wbxml' buffer with the WBXML Document to convert, and the wbxml_size with its size >>
        ...
        
        /* Converter parameters */
        params.gen_type = WBXML_ENCODER_XML_GEN_INDENT;
        params.indent = 1;
        params.keep_ignorable_ws = FALSE;

        /* Convert WBXML document */
        ret = wbxml2xml(wbxml, wbxml_size, &xml, &params);
        if (ret != WBXML_OK) {
            printf("wbxml2xml failed: %s\n", wbxml_errors_string(ret));
        }
        else {
            printf("wbxml2xml succeded: \n%s\n", xml);
    
            ...
            << Do what you have to do with this XML Buffer >>
            ...
                            
            /* Clean-up */
            wbxml_free(xml);
        }
        
        ...
                    
4.3.Tools
Table of Contents
4.3.1. #d3e826xml2wbxml 4.3.2. #d3e843wbxml2xml 
            This tools are used to encode an XML file to a WBXML file, and a WBXML file to an XML file.
        
4.3.1.xml2wbxml

                Convert an XML file to WBXML.
            
xml2wbxml  [-o output.wbxml] [-k] [-n] {input.xml}

                

                            -k : keep ignorable whitespaces (Default: ignore)
                        

                            -n : do NOT generate String Table (Default: generate)
                        

            
4.3.2.wbxml2xml

                Convert a WBXML file to XML.
            
wbxml2xml  [-o output.xml] [-m mode] [-i indent] [-k] {input.wbxml}

                

                            -m mode (Generation mode - Default: 1) with:
                            
                            
                                        0: Compact Generation
                                    
                            
                                        1: Indent Generation
                                    
                            
                                        2: Canonical Generation
                                    

                        

                            -i indent (Indent delta when using mode '1' - Default: 1)
                        

                            -k : keep ignorable whitespaces (Default: ignore)
                        

            

      Copyright  2003 Aymerick Jhanne
      All rights reserved.
      http://wbxmllib.jehanne.org
    
