home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2007 September / PCWSEP07.iso / Software / Linux / Linux Mint 3.0 Light / LinuxMint-3.0-Light.iso / casper / filesystem.squashfs / usr / include / libpurple / xmlnode.h < prev   
Encoding:
C/C++ Source or Header  |  2007-05-04  |  7.0 KB  |  266 lines
  1. /**
  2.  * @file xmlnode.h XML DOM functions
  3.  * @ingroup core
  4.  *
  5.  * purple
  6.  *
  7.  * Purple is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  */
  25. #ifndef _PURPLE_XMLNODE_H_
  26. #define _PURPLE_XMLNODE_H_
  27.  
  28. #ifdef __cplusplus
  29. extern "C" {
  30. #endif
  31.  
  32. /**
  33.  * The valid types for an xmlnode
  34.  */
  35. typedef enum _XMLNodeType
  36. {
  37.     XMLNODE_TYPE_TAG,        /**< Just a tag */
  38.     XMLNODE_TYPE_ATTRIB,        /**< Has attributes */
  39.     XMLNODE_TYPE_DATA        /**< Has data */
  40. } XMLNodeType;
  41.  
  42. /**
  43.  * An xmlnode.
  44.  */
  45. typedef struct _xmlnode xmlnode;
  46. struct _xmlnode
  47. {
  48.     char *name;            /**< The name of the node. */
  49.     char *xmlns;        /**< The namespace of the node */
  50.     XMLNodeType type;        /**< The type of the node. */
  51.     char *data;            /**< The data for the node. */
  52.     size_t data_sz;            /**< The size of the data. */
  53.     struct _xmlnode *parent;    /**< The parent node or @c NULL.*/
  54.     struct _xmlnode *child;        /**< The child node or @c NULL.*/
  55.     struct _xmlnode *lastchild;    /**< The last child node or @c NULL.*/
  56.     struct _xmlnode *next;        /**< The next node or @c NULL. */
  57. };
  58.  
  59. /**
  60.  * Creates a new xmlnode.
  61.  *
  62.  * @param name The name of the node.
  63.  *
  64.  * @return The new node.
  65.  */
  66. xmlnode *xmlnode_new(const char *name);
  67.  
  68. /**
  69.  * Creates a new xmlnode child.
  70.  *
  71.  * @param parent The parent node.
  72.  * @param name   The name of the child node.
  73.  *
  74.  * @return The new child node.
  75.  */
  76. xmlnode *xmlnode_new_child(xmlnode *parent, const char *name);
  77.  
  78. /**
  79.  * Inserts a node into a node as a child.
  80.  *
  81.  * @param parent The parent node to insert child into.
  82.  * @param child  The child node to insert into parent.
  83.  */
  84. void xmlnode_insert_child(xmlnode *parent, xmlnode *child);
  85.  
  86. /**
  87.  * Gets a child node named name.
  88.  *
  89.  * @param parent The parent node.
  90.  * @param name   The child's name.
  91.  *
  92.  * @return The child or NULL.
  93.  */
  94. xmlnode *xmlnode_get_child(const xmlnode *parent, const char *name);
  95.  
  96. /**
  97.  * Gets a child node named name in a namespace.
  98.  *
  99.  * @param parent The parent node.
  100.  * @param name   The child's name.
  101.  * @param xmlns  The namespace.
  102.  *
  103.  * @return The child or NULL.
  104.  */
  105. xmlnode *xmlnode_get_child_with_namespace(const xmlnode *parent, const char *name, const char *xmlns);
  106.  
  107. /**
  108.  * Gets the next node with the same name as node.
  109.  *
  110.  * @param node The node of a twin to find.
  111.  *
  112.  * @return The twin of node or NULL.
  113.  */
  114. xmlnode *xmlnode_get_next_twin(xmlnode *node);
  115.  
  116. /**
  117.  * Inserts data into a node.
  118.  *
  119.  * @param node   The node to insert data into.
  120.  * @param data   The data to insert.
  121.  * @param size   The size of the data to insert.  If data is
  122.  *               null-terminated you can pass in -1.
  123.  */
  124. void xmlnode_insert_data(xmlnode *node, const char *data, gssize size);
  125.  
  126. /**
  127.  * Gets data from a node.
  128.  *
  129.  * @param node The node to get data from.
  130.  *
  131.  * @return The data from the node.  You must g_free
  132.  *         this string when finished using it.
  133.  */
  134. char *xmlnode_get_data(xmlnode *node);
  135.  
  136. /**
  137.  * Sets an attribute for a node.
  138.  *
  139.  * @param node  The node to set an attribute for.
  140.  * @param attr  The name of the attribute.
  141.  * @param value The value of the attribute.
  142.  */
  143. void xmlnode_set_attrib(xmlnode *node, const char *attr, const char *value);
  144.  
  145. /**
  146.  * Sets a namespaced attribute for a node
  147.  *
  148.  * @param node  The node to set an attribute for.
  149.  * @param attr  The name of the attribute to set
  150.  * @param xmlns The namespace of the attribute to ste
  151.  * @param value The value of the attribute
  152.  */
  153. void xmlnode_set_attrib_with_namespace(xmlnode *node, const char *attr, const char *xmlns, const char *value);
  154.  
  155. /**
  156.  * Gets an attribute from a node.
  157.  *
  158.  * @param node The node to get an attribute from.
  159.  * @param attr The attribute to get.
  160.  *
  161.  * @return The value of the attribute.
  162.  */
  163. const char *xmlnode_get_attrib(xmlnode *node, const char *attr);
  164.  
  165. /**
  166.  * Gets a namespaced attribute from a node
  167.  *
  168.  * @param node  The node to get an attribute from.
  169.  * @param attr  The attribute to get
  170.  * @param xmlns The namespace of the attribute to get
  171.  *
  172.  * @return The value of the attribute/
  173.  */
  174. const char *xmlnode_get_attrib_with_namespace(xmlnode *node, const char *attr, const char *xmlns);
  175.  
  176. /**
  177.  * Removes an attribute from a node.
  178.  *
  179.  * @param node The node to remove an attribute from.
  180.  * @param attr The attribute to remove.
  181.  */
  182. void xmlnode_remove_attrib(xmlnode *node, const char *attr);
  183.  
  184. /**
  185.  * Removes a namespaced attribute from a node
  186.  *
  187.  * @param node  The node to remove an attribute from
  188.  * @param attr  The attribute to remove
  189.  * @param xmlns The namespace of the attribute to remove
  190.  */
  191. void xmlnode_remove_attrib_with_namespace(xmlnode *node, const char *attr, const char *xmlns);
  192.  
  193. /**
  194.  * Sets the namespace of a node
  195.  *
  196.  * @param node The node to qualify
  197.  * @param xmlns The namespace of the node
  198.  */
  199. void xmlnode_set_namespace(xmlnode *node, const char *xmlns);
  200.  
  201. /**
  202.  * Returns the namespace of a node
  203.  *
  204.  * @param node The node to get the namepsace from
  205.  * @return The namespace of this node
  206.  */
  207. const char *xmlnode_get_namespace(xmlnode *node);
  208.  
  209. /**
  210.  * Returns the node in a string of xml.
  211.  *
  212.  * @param node The starting node to output.
  213.  * @param len  Address for the size of the string.
  214.  *
  215.  * @return The node represented as a string.  You must
  216.  *         g_free this string when finished using it.
  217.  */
  218. char *xmlnode_to_str(xmlnode *node, int *len);
  219.  
  220. /**
  221.  * Returns the node in a string of human readable xml.
  222.  *
  223.  * @param node The starting node to output.
  224.  * @param len  Address for the size of the string.
  225.  *
  226.  * @return The node as human readable string including
  227.  *         tab and new line characters.  You must
  228.  *         g_free this string when finished using it.
  229.  */
  230. char *xmlnode_to_formatted_str(xmlnode *node, int *len);
  231.  
  232. /**
  233.  * Creates a node from a string of XML.  Calling this on the
  234.  * root node of an XML document will parse the entire document
  235.  * into a tree of nodes, and return the xmlnode of the root.
  236.  *
  237.  * @param str  The string of xml.
  238.  * @param size The size of the string, or -1 if @a str is
  239.  *             NUL-terminated.
  240.  *
  241.  * @return The new node.
  242.  */
  243. xmlnode *xmlnode_from_str(const char *str, gssize size);
  244.  
  245. /**
  246.  * Creates a new node from the source node.
  247.  *
  248.  * @param src The node to copy.
  249.  *
  250.  * @return A new copy of the src node.
  251.  */
  252. xmlnode *xmlnode_copy(const xmlnode *src);
  253.  
  254. /**
  255.  * Frees a node and all of it's children.
  256.  *
  257.  * @param node The node to free.
  258.  */
  259. void xmlnode_free(xmlnode *node);
  260.  
  261. #ifdef __cplusplus
  262. }
  263. #endif
  264.  
  265. #endif /* _PURPLE_XMLNODE_H_ */
  266.