>WBXML Library>
by Aymerick J?hanne
WBXML Library
C library for handling WBXML content
Aymerick J?hanne
Copyright ? 2003 Aymerick J?hanne
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.?
#overview
Overview
1.1.?
#d3e41
Components
1.2.?
#d3e64
Supported Languages
1.3.?
#d3e182
Project
1.4.?
#d3e191
Code Documentation
2.?
#install
Building and Installing
2.1.?
#d3e198
Linux
2.2.?
#d3e224
Windows
3.?
#using
Using WBXML Library
3.1.?
#d3e246
File convertion Tools (xml2wbxml, wbxml2xml)
3.2.?
#d3e254
Buffer convertion Library (libwbxml2_conv)
3.3.?
#d3e262
Low level WBXML Parser and Encoder (libwbxml2)
4.?
#reference
Reference
4.1.?
#d3e333
libwbxml2
4.1.1.?
#d3e335
WBXML Encoder
4.1.1.1.?
#d3e337
Encoder Creation
4.1.1.2.?
#d3e365
Encoder Initialization when generating WBXML or XML
4.1.1.3.?
#d3e394
Encoder Initialization when generating WBXML
4.1.1.4.?
#d3e410
Encoder Initialization when generating XML
4.1.1.5.?
#d3e444
Encoding Functions
4.1.1.6.?
#d3e485
Example
4.1.2.?
#d3e490
WBXML Parser
4.1.2.1.?
#d3e496
Parse to WBXML Tree
4.1.2.2.?
#d3e513
Parse with User Defined Callbacks
4.1.3.?
#d3e765
WBXML Tree
4.2.?
#d3e768
libwbxml2_conv
4.2.1.?
#d3e771
XML to WBXML Convertion
4.2.1.1.?
#d3e773
Prototype
4.2.1.2.?
#d3e788
XML2WBXMLParameters Structure
4.2.1.3.?
#d3e792
Example
4.2.2.?
#d3e797
WBXML to XML Convertion
4.2.2.1.?
#d3e799
Prototype
4.2.2.2.?
#d3e814
WBXML2XMLParameters Structure
4.2.2.3.?
#d3e818
Example
4.3.?
#d3e823
Tools
4.3.1.?
#d3e826
xml2wbxml
4.3.2.?
#d3e843
wbxml2xml
List of Examples
4.1.?
#d3e362
WBXML Encoder Creation/Destruction
4.2.?
#d3e487
WBXML Encoder Use
4.3.?
#d3e540
WBXML Parser Creation/Destruction
4.4.?
#d3e762
WBXML Parser use
4.5.?
#d3e794
XML to WBXML Convertion
4.6.?
#d3e820
WBXML to XML Convertion
Chapter?1.?Overview
Table of Contents
1.1.?
#d3e41
Components
1.2.?
#d3e64
Supported Languages
1.3.?
#d3e182
Project
1.4.?
#d3e191
Code 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.htm
WAP 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.htm
WAP 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.htm
WAP 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.htm
WAP 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.htm
WAP 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
Sp?cifications
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
Sp?cifications
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&amp;release_id=126876
here
CVS Access: :ext:anonymous@cvs.wbxmllib.sourceforge.net:/cvsroot/wbxmllib
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/wbxmllib
Browe the sources Online
1.4.?Code Documentation
The Code Documentation, generated by
http://www.doxygen.org/
doxygen
is
http://wbxmllib.sourceforge.net/html/index.html
HERE
!
Chapter?2.?Building and Installing
Table of Contents
2.1.?
#d3e198
Linux
2.2.?
#d3e224
Windows
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
Procedure?2.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'
Chapter?3.?Using WBXML Library
Table of Contents
3.1.?
#d3e246
File convertion Tools (xml2wbxml, wbxml2xml)
3.2.?
#d3e254
Buffer convertion Library (libwbxml2_conv)
3.3.?
#d3e262
Low 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'?part?of?an?WBXMLAttribute?contain?the?FULL?attribute?value.
????For?example,?with?the?attribute:?url="http://127.0.0.1/"
????if?the?'name'?part?is?this:
????????-?name->u.token->wbxmlCodePage:?0x00
????????-?name->u.token->wbxmlToken?:?0x4b
????????-?name->u.token->xmlName?:?"url"
????????-?name->u.token->xmlValue:?"http://"
????then,?'value'?is?still:?"http://127.0.0.1/"
????Of?course?(in?this?example)?it?should?be?better?to?have?the?wbxmlToken?0x4a?("url"?/?NULL).?So?you?mustn't?take?into
????account?the?'xmlValue'?field?for?'name'?to?get?the?Attribute?Value?of?this?Attribute.
????????????????????????????????
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.
Chapter?4.?Reference
Table of Contents
4.1.?
#d3e333
libwbxml2
4.1.1.?
#d3e335
WBXML Encoder
4.1.1.1.?
#d3e337
Encoder Creation
4.1.1.2.?
#d3e365
Encoder Initialization when generating WBXML or XML
4.1.1.3.?
#d3e394
Encoder Initialization when generating WBXML
4.1.1.4.?
#d3e410
Encoder Initialization when generating XML
4.1.1.5.?
#d3e444
Encoding Functions
4.1.1.6.?
#d3e485
Example
4.1.2.?
#d3e490
WBXML Parser
4.1.2.1.?
#d3e496
Parse to WBXML Tree
4.1.2.2.?
#d3e513
Parse with User Defined Callbacks
4.1.3.?
#d3e765
WBXML Tree
4.2.?
#d3e768
libwbxml2_conv
4.2.1.?
#d3e771
XML to WBXML Convertion
4.2.1.1.?
#d3e773
Prototype
4.2.1.2.?
#d3e788
XML2WBXMLParameters Structure
4.2.1.3.?
#d3e792
Example
4.2.2.?
#d3e797
WBXML to XML Convertion
4.2.2.1.?
#d3e799
Prototype
4.2.2.2.?
#d3e814
WBXML2XMLParameters Structure
4.2.2.3.?
#d3e818
Example
4.3.?
#d3e823
Tools
4.3.1.?
#d3e826
xml2wbxml
4.3.2.?
#d3e843
wbxml2xml
4.1.?libwbxml2
Table of Contents
4.1.1.?
#d3e335
WBXML Encoder
4.1.1.1.?
#d3e337
Encoder Creation
4.1.1.2.?
#d3e365
Encoder Initialization when generating WBXML or XML
4.1.1.3.?
#d3e394
Encoder Initialization when generating WBXML
4.1.1.4.?
#d3e410
Encoder Initialization when generating XML
4.1.1.5.?
#d3e444
Encoding Functions
4.1.1.6.?
#d3e485
Example
4.1.2.?
#d3e490
WBXML Parser
4.1.2.1.?
#d3e496
Parse to WBXML Tree
4.1.2.2.?
#d3e513
Parse with User Defined Callbacks
4.1.3.?
#d3e765
WBXML Tree
4.1.1.?WBXML Encoder
Table of Contents
4.1.1.1.?
#d3e337
Encoder Creation
4.1.1.2.?
#d3e365
Encoder Initialization when generating WBXML or XML
4.1.1.3.?
#d3e394
Encoder Initialization when generating WBXML
4.1.1.4.?
#d3e410
Encoder Initialization when generating XML
4.1.1.5.?
#d3e444
Encoding Functions
4.1.1.6.?
#d3e485
Example
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
Example?4.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
Example?4.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.?
#d3e496
Parse to WBXML Tree
4.1.2.2.?
#d3e513
Parse 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
Example?4.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_LONG
charset
;
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_BOOL
empty
;
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_BOOL
empty
;
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_ULONG
start
;
WB_ULONG
length
;
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
Example?4.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.?
#d3e771
XML to WBXML Convertion
4.2.1.1.?
#d3e773
Prototype
4.2.1.2.?
#d3e788
XML2WBXMLParameters Structure
4.2.1.3.?
#d3e792
Example
4.2.2.?
#d3e797
WBXML to XML Convertion
4.2.2.1.?
#d3e799
Prototype
4.2.2.2.?
#d3e814
WBXML2XMLParameters Structure
4.2.2.3.?
#d3e818
Example
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.?
#d3e773
Prototype
4.2.1.2.?
#d3e788
XML2WBXMLParameters Structure
4.2.1.3.?
#d3e792
Example
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
Example?4.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.?
#d3e799
Prototype
4.2.2.2.?
#d3e814
WBXML2XMLParameters Structure
4.2.2.3.?
#d3e818
Example
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
Example?4.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.?
#d3e826
xml2wbxml
4.3.2.?
#d3e843
wbxml2xml
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 J?hanne
All rights reserved.
http://wbxmllib.jehanne.org
