wbxml_tree.h

WAP Binary XML 简单地说

 * @param len        Text content length
 * @return The newly created Tree Node, or NULL if not enough memory
 */
WBXML_DECLARE(WBXMLTreeNode *) wbxml_tree_node_create_text(const WB_UTINY *text,
                                                           WB_ULONG len);

/**
 * @brief Create a CDATA Node structure
 * @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_cdata(const WB_UTINY *text,
                                                            WB_ULONG len);

/**
 * @brief Create a Tree Node structure
 * @param root Root node for this Tree
 * @param lang Language table to use
 * @param orig_charset Original charset
 * @return The newly created Tree Node, or NULL if not enough memory
 */
WBXML_DECLARE(WBXMLTreeNode *) wbxml_tree_node_create_tree(WBXMLTreeNode *root,
                                                           WBXMLLanguage lang,
                                                           WBXMLCharsetMIBEnum orig_charset);

/**
 * @brief Add a Child node
 * @param parent Parent node
 * @param node   Child node to add
 * @return TRUE if added or FALSE if error
 */
WBXML_DECLARE(WB_BOOL) wbxml_tree_node_add_child(WBXMLTreeNode *parent,
                                                 WBXMLTreeNode *node);

/**
 * @brief Add a WBXML Attribute to a Tree Node structure
 * @param node The Tree Node to modify
 * @param attr The WBXML Attribute to add
 * @return WBXML_OK if no error, an error code otherwise
 * @note This is only meanfull for an element node
 */
WBXML_DECLARE(WBXMLError) wbxml_tree_node_add_attr(WBXMLTreeNode *node,
                                                   WBXMLAttribute *attr);

/**
 * @brief Add a WBXML Attributes list to a Tree Node structure
 * @param node  The Tree Node to modify
 * @param attrs The WBXML Attributes to add
 * @return WBXML_OK if no error, an error code otherwise
 * @note This is only meanfull for an element node
 */
WBXML_DECLARE(WBXMLError) wbxml_tree_node_add_attrs(WBXMLTreeNode *node,
                                                    WBXMLAttribute **attrs);

/**
 * @brief Add an XML Attribute to a Tree Node structure
 * @param lang_table Language table
 * @param node The Tree Node to modify
 * @param name The XML Attribute name
 * @param value The XML Attribute value
 * @return WBXML_OK if no error, an error code otherwise
 * @note This is only meanfull for an element node
 */
WBXML_DECLARE(WBXMLError) wbxml_tree_node_add_xml_attr(const WBXMLLangEntry *lang_table,
                                                       WBXMLTreeNode *node,
                                                       const WB_UTINY *name,
                                                       const WB_UTINY *value);

/**
 * @brief Add an XML Attributes list to a Tree Node structure
 * @param lang_table Language table
 * @param node  The Tree Node to modify
 * @param attrs The XML Attributes to add
 * @return WBXML_OK if no error, an error code otherwise
 * @note This is only meanfull for an element node
 */
WBXML_DECLARE(WBXMLError) wbxml_tree_node_add_xml_attrs(const WBXMLLangEntry *lang_table,
                                                        WBXMLTreeNode *node,
                                                        const WB_UTINY **attrs);

/**
 * @brief Get an Element Node, given the Element Name
 * @param node   The Tree Node where to start searching
 * @param name   The Element Name we are searching
 * @param recurs If FALSE, only search into direct childs of 'node'
 * @return The found Tree Node, or NULL if not found
 */
WBXML_DECLARE(WBXMLTreeNode *) wbxml_tree_node_elt_get_from_name(WBXMLTreeNode *node,
                                                                 const char *name,
                                                                 WB_BOOL recurs);

#if defined ( WBXML_SUPPORT_SYNCML )

/**
 * @brief Get the SyncML Data Type of this Tree Node
 * @param node The Tree Node
 * @return The SyncML Data Type of this Tree Node (cf: WBXMLSyncMLDataType enum)
 * @note If no specific Data Type is found, this function returns 'WBXML_SYNCML_DATA_TYPE_NORMAL'
 */
WBXML_DECLARE(WBXMLSyncMLDataType) wbxml_tree_node_get_syncml_data_type(WBXMLTreeNode *node);

#endif /* WBXML_SUPPORT_SYNCML */

/**
 * @brief Check if a node have an Element Node in its children list
 * @param node The Tree Node
 * @return YES if one of the node children is an Element, FALSE otherwise
 */
WBXML_DECLARE(WB_BOOL) wbxml_tree_node_have_child_elt(WBXMLTreeNode *node);

/**
 * @brief Get all children from node
 * @param node The Tree Node
 * @return A list of all children belonging to this node, or NULL if no children found
 */
WBXML_DECLARE(WBXMLList*) wbxml_tree_node_get_all_children(WBXMLTreeNode *node);


/**
 * @brief Create a Tree structure
 * @param lang Tree Language
 * @param orig_charset Original tree charset
 * @return The newly created Tree, or NULL if not enough memory
 * @note The 'orig_charset' is used for further Tree encoding, it does NOT set
 *       the internal Tree representation charset (UTF8 is always used).
 */
WBXML_DECLARE(WBXMLTree *) wbxml_tree_create(WBXMLLanguage lang,
                                             WBXMLCharsetMIBEnum orig_charset);

/**
 * @brief Destroy a Tree structure, and all its nodes
 * @param tree The Tree structure to destroy
 */
WBXML_DECLARE(void) wbxml_tree_destroy(WBXMLTree *tree);

/**
 * @brief Add a Node to a Tree
 * @param tree   The Tree to modify
 * @param parent Parent of the new Node (ie: Position where to add the new Node in Tree)
 * @param node   The new Tree Node to add
 * @return TRUE is added, or FALSE if error.
 * @note If 'parent' is NULL: if 'tree' already have a Root Element this function returns FALSE, else 'node' becomes the Root Element of 'tree'
 */
WBXML_DECLARE(WB_BOOL) wbxml_tree_add_node(WBXMLTree *tree,
                                           WBXMLTreeNode *parent,
                                           WBXMLTreeNode *node);

/**
 * @brief Extract a Tree Node from its WBXML Tree
 * @param tree  The Tree to modify
 * @param node  The Tree Node to extract
 * @return WBXML_OK if no error, an error code otherwise
 * @note The node is extracted but not freed
 */
WBXML_DECLARE(WBXMLError) wbxml_tree_extract_node(WBXMLTree *tree,
                                                  WBXMLTreeNode *node);

/**
 * @brief Add an Element Node to Tree, given its WBXML Tag
 * @param tree   The Tree to modify
 * @param parent Parent of the new Node (ie: Position where to add the new Node in Tree)
 * @param tag    Element to add
 * @return The newly created node, or NULL if error.
 * @note If 'parent' is NULL: if 'tree' already have a Root Element this function returns NULL, else 'node' becomes the Root Element of 'tree'
 */
WBXML_DECLARE(WBXMLTreeNode *) wbxml_tree_add_elt(WBXMLTree *tree,
                                                  WBXMLTreeNode *parent,
                                                  WBXMLTag *tag);

/**
 * @brief Add a Tag Element Node to Tree, with its WBXML Attributes
 * @param tree   The Tree to modify
 * @param parent Parent of the new Node (ie: Position where to add the new Node in Tree)
 * @param tag    Element to add
 * @param attrs  Element attributes
 * @return The newly created node, or NULL if error.
 * @note If 'parent' is NULL: if 'tree' already have a Root Element this function returns NULL, else 'node' becomes the Root Element of 'tree'
 */
WBXML_DECLARE(WBXMLTreeNode *) wbxml_tree_add_elt_with_attrs(WBXMLTree *tree,
                                                             WBXMLTreeNode *parent,
                                                             WBXMLTag *tag,
                                                             WBXMLAttribute **attrs);

/**
 * @brief Add an Element Node to a Tree, given its XML Name
 * @param tree   The Tree to modify
 * @param parent Parent of the new Node (ie: Position where to add the new Node in Tree)
 * @param name   XML element name to add
 * @return The newly created node, or NULL if error.
 * @note If 'parent' is NULL: if 'tree' already have a Root Element this function returns NULL, else 'node' becomes the Root Element of 'tree'
 */
WBXML_DECLARE(WBXMLTreeNode *) wbxml_tree_add_xml_elt(WBXMLTree *tree,
                                                      WBXMLTreeNode *parent,
                                                      WB_UTINY *name);

/**
 * @brief Add an Element Node to Tree, with its WBXML Attributes, given there XML values
 * @param tree   The Tree to modify
 * @param parent Parent of the new Node (ie: Position where to add the new Node in Tree)
 * @param name   XML element name to add
 * @param attrs  XML element attributes
 * @return The newly created node, or NULL if error.
 * @note If 'parent' is NULL: if 'tree' already have a Root Element this function returns NULL, else 'node' becomes the Root Element of 'tree'
 */
WBXML_DECLARE(WBXMLTreeNode *) wbxml_tree_add_xml_elt_with_attrs(WBXMLTree *tree,
                                                                 WBXMLTreeNode *parent,
                                                                 WB_UTINY *name,
                                                                 const WB_UTINY **attrs);

/**
 * @brief Add a Text Node to Tree
 * @param tree   The Tree to modify
 * @param parent Parent of the new Node (ie: Position where to add the new Node in Tree)
 * @param text   Text to add
 * @param len    Text length
 * @return The newly created node, or NULL if error.
 * @note If 'parent' is NULL: if 'tree' already have a Root Element this function returns NULL, else 'node' becomes the Root Element of 'tree'
 */
WBXML_DECLARE(WBXMLTreeNode *) wbxml_tree_add_text(WBXMLTree *tree,
                                                   WBXMLTreeNode *parent,
                                                   const WB_UTINY *text,
                                                   WB_ULONG len);

/**
 * @brief Add CDATA Node to Tree
 * @param tree   The Tree to modify
 * @param parent Parent of the new Node (ie: Position where to add the new Node in Tree)
 * @return The newly created node, or NULL if error.
 * @note If 'parent' is NULL: if 'tree' already have a Root Element this function returns NULL, else 'node' becomes the Root Element of 'tree'
 */
WBXML_DECLARE(WBXMLTreeNode *) wbxml_tree_add_cdata(WBXMLTree *tree,
                                                    WBXMLTreeNode *parent);

/** @todo wbxml_tree_add_cdata_with_text() */

/**
 * @brief Add a Tree Node to Tree
 * @param tree     The Tree to modify
 * @param parent   Parent of the new Node (ie: Position where to add the new Node in Tree)
 * @param new_tree The new Tree to add (will be freed when destroying the main Tree, so caller must not free it)
 * @return The newly created node, or NULL if error.
 * @note If 'parent' is NULL: if 'tree' already have a Root Element this function returns NULL, else 'node' becomes the Root Element of 'tree'
 */
WBXML_DECLARE(WBXMLTreeNode *) wbxml_tree_add_tree(WBXMLTree *tree,
                                                   WBXMLTreeNode *parent,
                                                   WBXMLTree *new_tree);

/**
 * @brief Add an Element Node to a Tree, given its XML Name, its attributes and a text content
 * @param tree   The Tree to modify
 * @param parent Parent of the new Node (ie: Position where to add the new Node in Tree)
 * @param name   XML element name to add
 * @param attrs  XML element attributes
 * @param text   Text content for this new element
 * @param len    Text content length
 * @return The newly created node, or NULL if error.
 * @note If 'parent' is NULL: if 'tree' already have a Root Element this function returns NULL, else 'node' becomes the Root Element of 'tree'
 */
WBXML_DECLARE(WBXMLTreeNode *) wbxml_tree_add_xml_elt_with_attrs_and_text(WBXMLTree *tree,
                                                                          WBXMLTreeNode *parent,
                                                                          WB_UTINY *name,
                                                                          const WB_UTINY **attrs,
                                                                          const WB_UTINY *text,
                                                                          WB_ULONG len);

/** @} */

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* WBXML_TREE_H */