wbxml_tree.h

WAP Binary XML 简单地说

/*
 * libwbxml, the WBXML Library.
 * Copyright (C) 2002-2005 Aymerick Jehanne <[e-mail]>
 * 
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 * 
 * LGPL v2.1: http://www.gnu.org/copyleft/lesser.txt
 * 
 * Contact: [e-mail]
 * Home: http://libwbxml.aymerick.com
 */
 
/**
 * @file wbxml_tree.h
 * @ingroup wbxml_tree
 *
 * @author Aymerick Jehanne <[e-mail]>
 * @date 03/02/16
 *
 * @brief WBXML Tree
 */

#ifndef WBXML_TREE_H
#define WBXML_TREE_H

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

/** @addtogroup wbxml_tree
 *  @{ 
 */


/****************************************************
 *	WBXML Tree Structures
 */
  

/**
 * @brief WBXML Tree Node Type
 */
typedef enum WBXMLTreeNodeType_e
{
    WBXML_TREE_ELEMENT_NODE = 0, /**< Element Node */
    WBXML_TREE_TEXT_NODE,        /**< Text Node */
    WBXML_TREE_CDATA_NODE,       /**< CDATA Node */
    WBXML_TREE_PI_NODE,          /**< PI Node */
    WBXML_TREE_TREE_NODE         /**< WBXML Tree Node */
} WBXMLTreeNodeType;

/**
 * @brief WBXML Tree Node structure
 */
typedef struct WBXMLTreeNode_s
{
    WBXMLTreeNodeType   type;       /**< Node Type */
    WBXMLTag            *name;      /**< Node Name (if type is 'WBXML_TREE_ELEMENT_NODE') */
    WBXMLList           *attrs;     /**< Node Attributes (if type is 'WBXML_TREE_ELEMENT_NODE') */
    WBXMLBuffer         *content;   /**< Node Content (if  type is 'WBXML_TREE_TEXT_NODE')  */
    struct WBXMLTree_s  *tree;      /**< Node Tree (if  type is 'WBXML_TREE_TREE_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;


/**
 * @brief WBXML Tree structure
 * 
 * This structure is created when parsing a WBXML or XML document, thanks to
 * the functions wbxml_tree_from_wbxml() and wbxml_tree_from_xml().
 *
 * It represents the parsed document, and have this fields:
 *   - lang: the language table of the parsed document (in wbxml_tables.c)
 *   - root: the root element of the Tree representing the parsed document
 *   - orig_charset: the original charset encoding of the parsed document
 *
 * @note All the strings inside the WBXML Tree are encoded into UTF-8
 */
typedef struct WBXMLTree_s
{    
    const WBXMLLangEntry *lang;         /**< Language Table */
    WBXMLTreeNode        *root;         /**< Root Element */
    WBXMLCharsetMIBEnum   orig_charset; /**< Charset encoding of original document */
} WBXMLTree;


/** 
 * WBXML Tree Clb Context Structure
 * @note Used by WBXML Tree Callbacks ('wbxml_tree_clb_wbxml.h' and 'wbxml_tree_clb_xml.h')
 */
typedef struct WBXMLTreeClbCtx_s {
    /* For XML and WBXML Clb */
    WBXMLTree     *tree;          /**< The WBXML Tree we are constructing */
    WBXMLTreeNode *current;       /**< Current Tree Node */
    WBXMLError     error;         /**< Error while parsing Document */
    /* For XML Clb */
    WB_ULONG       skip_lvl;      /**< Used to skip a whole XML node (used for SyncML) */
    WB_LONG        skip_start;    /**< Starting Skipping position in XML Document (used for SyncML) */
    WB_UTINY      *input_buff;    /**< Pointer to Input Buffer */
#if defined( HAVE_EXPAT )
    XML_Parser     xml_parser;    /**< Pointer to Expat XML Parser */
    WB_BOOL        expat_utf16;   /**< Is Expat compiled to output UTF-16 ? */
#endif /* HAVE_EXPAT */ 
} WBXMLTreeClbCtx;


#if defined ( WBXML_SUPPORT_SYNCML )
/**
 * SyncML Data Type (the type of data inside <Data> element)
 */
typedef enum WBXMLSyncMLDataType_e {
    WBXML_SYNCML_DATA_TYPE_NORMAL = 0,      /**< Not specific Data Type */
    WBXML_SYNCML_DATA_TYPE_WBXML,           /**< application/vnd.syncml-devinf+wbxml (WBXML Document) */
    WBXML_SYNCML_DATA_TYPE_CLEAR,			/**< text/clear */
    WBXML_SYNCML_DATA_TYPE_DIRECTORY_VCARD, /**< text/directory;profile=vCard */
    WBXML_SYNCML_DATA_TYPE_VCARD,           /**< text/x-vcard */
    WBXML_SYNCML_DATA_TYPE_VCALENDAR,       /**< text/x-vcalendar */
    WBXML_SYNCML_DATA_TYPE_VOBJECT          /**< Hack: we assume that any <Data> inside a <Replace> or <Add> Item is a vObjec (vCard / vCal / ...) */
} WBXMLSyncMLDataType;
#endif /* WBXML_SUPPORT_SYNCML */


/****************************************************
 *  WBXML Tree Building Functions
 */

/**
 * @brief Parse a WBXML document, using internal callbacks (in wbxml_tree_clb_wbxml.c), and construct a WBXML Tree
 * @param wbxml     [in]  The WBXML document to parse
 * @param wbxml_len [in]  The WBXML document length
 * @param lang      [in]  Can be used to force parsing of a given Language (set it to WBXML_LANG_UNKNOWN if you don't want to force anything)
 * @param tree      [out] The resulting WBXML Tree 
 * @result Return WBXML_OK if no error, an error code otherwise
 */
WBXML_DECLARE(WBXMLError) wbxml_tree_from_wbxml(WB_UTINY *wbxml,
                                                WB_ULONG wbxml_len,
                                                WBXMLLanguage lang,
                                                WBXMLTree **tree);

/**
 * @brief Convert a WBXML Tree to a WBXML document
 * @param tree      [in]  The WBXML Tree to convert
 * @param wbxml     [out] The resulting WBXML document
 * @param wbxml_len [out] The resulting WBXML document length
 * @param params    [in]  Parameters (if NULL, default values are used)
 * @result Return WBXML_OK if no error, an error code otherwise
 */
WBXML_DECLARE(WBXMLError) wbxml_tree_to_wbxml(WBXMLTree *tree,
                                              WB_UTINY **wbxml,
                                              WB_ULONG  *wbxml_len,
                                              WBXMLGenWBXMLParams *params);

/**
 * @brief Parse an XML document, using internal callbacks (in wbxml_tree_clb_xml.c), and construct a WBXML Tree
 * @param xml     [in]  The XML document to parse
 * @param xml_len [in]  Length of the XML document
 * @param tree    [out] The resulting WBXML Tree 
 * @result Return WBXML_OK if no error, an error code otherwise
 * @note Needs 'HAVE_EXPAT' compile flag
 */
WBXML_DECLARE(WBXMLError) wbxml_tree_from_xml(WB_UTINY *xml,
                                              WB_ULONG xml_len,
                                              WBXMLTree **tree);

/**
 * @brief Convert a WBXML Tree to an XML document
 * @param tree      [in]  The WBXML Tree to convert
 * @param wbxml     [out] The resulting XML document
 * @param wbxml_len [out] The resulting XML document length
 * @param params    [in]  Parameters (if NULL, default values are used)
 * @result Return WBXML_OK if no error, an error code otherwise
 */
WBXML_DECLARE(WBXMLError) wbxml_tree_to_xml(WBXMLTree *tree,
                                            WB_UTINY **xml,
                                            WB_ULONG  *xml_len,
                                            WBXMLGenXMLParams *params);

/** @todo Libxml support ! */
#if defined( HAVE_LIBXML )

/**
 * @brief Parse a LibXML document, and construct the corresponding WBXML Tree
 * @param libxml_doc [in]  The LibXML document to parse
 * @param tree       [out] The resulting WBXML Tree 
 * @result Return WBXML_OK if no error, an error code otherwise
 * @note Needs 'HAVE_LIBXML' compile flag
 */
WBXML_DECLARE(WBXMLError) wbxml_tree_from_libxml_doc(xmlDocPtr libxml_doc,
                                                     WBXMLTree **tree);

/**
 * @brief Parse a WBXML Tree, and construct the corresponding LibXML document
 * @param tree       [in]  The WBXML Tree to parse
 * @param libxml_doc [out] The resulting LibXML document
 * @result Return WBXML_OK if no error, an error code otherwise
 * @note Needs 'HAVE_LIBXML' compile flag
 */
WBXML_DECLARE(WBXMLError) wbxml_tree_to_libxml_doc(WBXMLTree *tree,
                                                   xmlDocPtr *libxml_doc);

#endif /* HAVE_LIBXML */


/****************************************************
 *	WBXML Tree Functions
 */

/**
 * @brief Create a Tree Node structure
 * @param type Node type
 * @return The newly created Tree Node, or NULL if not enough memory
 */
WBXML_DECLARE(WBXMLTreeNode *) wbxml_tree_node_create(WBXMLTreeNodeType type);

/**
 * @brief Destroy a Tree Node structure
 * @param node The Tree Node structure to destroy
 * @note The Node is freed, but not extracted from its WBXML Tree (use wbxml_tree_extract_node() before)
 */
WBXML_DECLARE(void) wbxml_tree_node_destroy(WBXMLTreeNode *node);

/**
 * @brief Destroy a Tree Node structure (used for wbxml_list_destroy())
 * @paramnode The Tree Node structure to destroy
 */
WBXML_DECLARE(void) wbxml_tree_node_destroy_item(void *node);

/**
 * @brief Destroy a Tree Node structure, and all its children
 * @param node The Tree Node structure to destroy
 * @note The Node (and its sub-tree) is freed, but not extracted from its WBXML Tree (use wbxml_tree_extract_node() before)
 */
WBXML_DECLARE(void) wbxml_tree_node_destroy_all(WBXMLTreeNode *node);

/**
 * @brief Create a Tree Node structure, given the XML node name
 * @param lang_table Language table
 * @param name       XML node name
 * @return The newly created Tree Node, or NULL if not enough memory
 */
WBXML_DECLARE(WBXMLTreeNode *) wbxml_tree_node_create_xml_elt(const WBXMLLangEntry *lang_table,
                                                              const WB_UTINY *name);

/**
 * @brief Create a Tree Node structure, given the XML node name and text content
 * @param lang_table Language table
 * @param name       XML node name
 * @param text       Text content
 * @param len        Text content length
 * @return The newly created Tree Node, or NULL if not enough memory
 */
WBXML_DECLARE(WBXMLTreeNode *) wbxml_tree_node_create_xml_elt_with_text(const WBXMLLangEntry *lang_table,
                                                                        const WB_UTINY *name,
                                                                        const WB_UTINY *text,
                                                                        WB_ULONG len);

/**
 * @brief Create a Text Node structure
 * @param text       Text content