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
List of Examples
Table of Contents
The WBXML Library consists of 2 libraries:
The main library, which contains the WBXML Parser and the WBXML Encoder. This is a standalone library.
A wrapper arround libwbxml2 to convert from XML to WBXML and from WBXML to XML. This is linked with libwbxml2 and Expat.
Two tools are also provided:
Converts a XML document to a WBXML document.
Converts a WBXML document to a XML document.
WAP Forum Specifications
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)
WBXML 1.1 - SPEC-WBXML-19990616.pdf (Tested)
WML 1.1 - SPEC-WML-19990616.pdf (Untested)
CHANNEL 1.1 - SPEC-WTA-19990716.pdf (Untested)
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)
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)
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)
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)
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)
Wireless-Village Spécifications
WV CSP 1.1
WSP 1.1 - WV_CSP_WBXML_v1.1.pdf (Untested)
The WBXML Library project is hosted on SourceForge
The latests package can be downloaded: here
CVS Access: :ext:anonymous@cvs.wbxmllib.sourceforge.net:/cvsroot/wbxmllib
You must have the 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 |
---|---|
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
The 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'
Table of Contents
There are three ways of using the WBXML Library:
This are the high level components of the WBXML Library. This tools need the libwbxml2_conv, libwbxml2 and Expat libraries.
There are two Convertion Tools:
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 Expat libraries.
There are two Convertion Functions:
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:
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.
This module contains all the WBXML Tables. It defines too the structures:
This module defines the WBXML Elements used in the WBXML Tree structure:
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:
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:
typedef struct WBXMLAttribute_s { WBXMLAttributeName *name; /* Attribute Name */ WBXMLBuffer *value; /* Full Attribute Value */ } WBXMLAttribute;The WBXMLAttribute contains:
![]() | Warning |
---|---|
|
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;
The WBXML Encoder is used to encode a WBXML Tree into:
The WBXML Parser can be used in two ways:
Table of Contents
Table of Contents
Table of Contents
This two functions permit to create and destroy WBXML Encoder instances.
#include <wbxml.h>
WBXMLEncoder *wbxml_encoder_create
();
void;
Create a WBXML Encoder instance. Returns NULL if not enough memory.
#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.
This functions that initialize the WBXML Encoder are usefull when generating WBXML and XML.
#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].
#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].
This functions that initialize the WBXML Encoder are only usefull when generating WBXML.
This functions that initialize the WBXML Encoder are only usefull when generating XML.
#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:
This are the main functions to encode a WBXMLTree.
#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.
#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.
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); }
Table of Contents
There are two ways of using the WBXML Parser
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.
This two functions permit to create and destroy WBXML Parser instances.
#include <wbxml.h>
WBXMLParser *wbxml_parser_create
();
void;
Create a WBXML Parser instance. Returns NULL if not enough memory.
#include <wbxml.h>
void wbxml_parser_destroy
(parser);
WBXMLParser *parser;
Destroy a WBXML Parser instance. The User Data is not destroyed by this function.
This functions are used to initialise the Parser.
#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.
#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.
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.
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.
void WBXMLEndElementHandler
(ctx, localName, empty);
void *ctx;
WBXMLTag *localName;
WB_BOOLempty;
This Callback function is called when parsing a WBXML end Element.
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.
void WBXMLProcessingInstructionHandler
(ctx, target, data);
void *ctx;
const WB_UTINY *target;
WB_UTINY *data;
This Callback function is called when parsing a Processing Instruction.
#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).
This functions are used to retrieve informations while or after Parsing.
#include <wbxml.h>
WB_ULONG wbxml_parser_get_wbxml_public_id
(parser);
WBXMLParser *parser;
Get the WBXML Public ID of current parsing WBXML document.
#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.
#include <wbxml.h>
WB_UTINY wbxml_parser_get_wbxml_version
(parser);
WBXMLParser *parser;
Get the WBXML Version of current parsing WBXML document.
#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.
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; }
Table of Contents
This functions permit to convert directly XML to WBXML, and WBXML to XML.
Table of Contents
#include <wbxml_conv.h>
WBXMLError xml2wbxml
(xml, wbxml, wbxml_len, params);
WB_UTINY *xml;
WB_UTINY **wbxml;
WB_ULONG *wbxml_len;
XML2WBXMLParameters *params;
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;
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, ¶ms); 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); } ...
Table of Contents
#include <wbxml_conv.h>
WBXMLError wbxml2xml
(wbxml, wbxml_len, xml, params);
WB_UTINY *wbxml;
WB_ULONG wbxml_len;
WB_UTINY **xml;
WBXML2XMLParameters *params;
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;
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, ¶ms); 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); } ...
This tools are used to encode an XML file to a WBXML file, and a WBXML file to an XML file.
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)
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)