libpurple/xmlnode.h

   1 /**
   2  * @file xmlnode.h XML DOM functions
   3  * @ingroup core
   4  */
   5
   6 /* purple
   7  *
   8  * Purple is the legal property of its developers, whose names are too numerous
   9  * to list here.  Please refer to the COPYRIGHT file distributed with this
  10  * source distribution.
  11  *
  12  * This program is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU General Public License as published by
  14  * the Free Software Foundation; either version 2 of the License, or
  15  * (at your option) any later version.
  16  *
  17  * This program is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License
  23  * along with this program; if not, write to the Free Software
  24  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  25  */
  26 #ifndef _PURPLE_XMLNODE_H_
  27 #define _PURPLE_XMLNODE_H_
  28
  29 #include <glib.h>
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 /**
  36  * The valid types for an xmlnode
  37  */
  38 typedef enum _XMLNodeType
  39 {
  40         XMLNODE_TYPE_TAG,               /**< Just a tag */
  41         XMLNODE_TYPE_ATTRIB,            /**< Has attributes */
  42         XMLNODE_TYPE_DATA               /**< Has data */
  43 } XMLNodeType;
  44
  45 /**
  46  * An xmlnode.
  47  */
  48 typedef struct _xmlnode xmlnode;
  49 struct _xmlnode
  50 {
  51         char *name;                     /**< The name of the node. */
  52         char *xmlns;            /**< The namespace of the node */
  53         XMLNodeType type;               /**< The type of the node. */
  54         char *data;                     /**< The data for the node. */
  55         size_t data_sz;                 /**< The size of the data. */
  56         xmlnode *parent;            /**< The parent node or @c NULL.*/
  57         xmlnode *child;             /**< The child node or @c NULL.*/
  58         xmlnode *lastchild;         /**< The last child node or @c NULL.*/
  59         xmlnode *next;              /**< The next node or @c NULL. */
  60         char *prefix;               /**< The namespace prefix if any. */
  61         GHashTable *namespace_map;  /**< The namespace map. */
  62 };
  63
  64 /**
  65  * Creates a new xmlnode.
  66  *
  67  * @param name The name of the node.
  68  *
  69  * @return The new node.
  70  */
  71 xmlnode *xmlnode_new(const char *name);
  72
  73 /**
  74  * Creates a new xmlnode child.
  75  *
  76  * @param parent The parent node.
  77  * @param name   The name of the child node.
  78  *
  79  * @return The new child node.
  80  */
  81 xmlnode *xmlnode_new_child(xmlnode *parent, const char *name);
  82
  83 /**
  84  * Inserts a node into a node as a child.
  85  *
  86  * @param parent The parent node to insert child into.
  87  * @param child  The child node to insert into parent.
  88  */
  89 void xmlnode_insert_child(xmlnode *parent, xmlnode *child);
  90
  91 /**
  92  * Gets a child node named name.
  93  *
  94  * @param parent The parent node.
  95  * @param name   The child's name.
  96  *
  97  * @return The child or NULL.
  98  */
  99 xmlnode *xmlnode_get_child(const xmlnode *parent, const char *name);
 100
 101 /**
 102  * Gets a child node named name in a namespace.
 103  *
 104  * @param parent The parent node.
 105  * @param name   The child's name.
 106  * @param xmlns  The namespace.
 107  *
 108  * @return The child or NULL.
 109  */
 110 xmlnode *xmlnode_get_child_with_namespace(const xmlnode *parent, const char *name, const char *xmlns);
 111
 112 /**
 113  * Gets the next node with the same name as node.
 114  *
 115  * @param node The node of a twin to find.
 116  *
 117  * @return The twin of node or NULL.
 118  */
 119 xmlnode *xmlnode_get_next_twin(xmlnode *node);
 120
 121 /**
 122  * Inserts data into a node.
 123  *
 124  * @param node   The node to insert data into.
 125  * @param data   The data to insert.
 126  * @param size   The size of the data to insert.  If data is
 127  *               null-terminated you can pass in -1.
 128  */
 129 void xmlnode_insert_data(xmlnode *node, const char *data, gssize size);
 130
 131 /**
 132  * Gets (escaped) data from a node.
 133  *
 134  * @param node The node to get data from.
 135  *
 136  * @return The data from the node or NULL. This data is in raw escaped format.
 137  *         You must g_free this string when finished using it.
 138  */
 139 char *xmlnode_get_data(const xmlnode *node);
 140
 141 /**
 142  * Gets unescaped data from a node.
 143  *
 144  * @param node The node to get data from.
 145  *
 146  * @return The data from the node, in unescaped form.   You must g_free
 147  *         this string when finished using it.
 148  */
 149 char *xmlnode_get_data_unescaped(const xmlnode *node);
 150
 151 /**
 152  * Sets an attribute for a node.
 153  *
 154  * @param node  The node to set an attribute for.
 155  * @param attr  The name of the attribute.
 156  * @param value The value of the attribute.
 157  */
 158 void xmlnode_set_attrib(xmlnode *node, const char *attr, const char *value);
 159
 160 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_XMLNODE_C_)
 161 /**
 162  * Sets a prefixed attribute for a node
 163  *
 164  * @param node   The node to set an attribute for.
 165  * @param attr   The name of the attribute to set
 166  * @param prefix The prefix of the attribute to ste
 167  * @param value  The value of the attribute
 168  *
 169  * @deprecated Use xmlnode_set_attrib_full instead.
 170  */
 171 void xmlnode_set_attrib_with_prefix(xmlnode *node, const char *attr, const char *prefix, const char *value);
 172
 173 /**
 174  * Sets a namespaced attribute for a node
 175  *
 176  * @param node  The node to set an attribute for.
 177  * @param attr  The name of the attribute to set
 178  * @param xmlns The namespace of the attribute to ste
 179  * @param value The value of the attribute
 180  *
 181  * @deprecated Use xmlnode_set_attrib_full instead.
 182  */
 183 void xmlnode_set_attrib_with_namespace(xmlnode *node, const char *attr, const char *xmlns, const char *value);
 184 #endif /* PURPLE_DISABLE_DEPRECATED */
 185
 186 /**
 187  * Sets a namespaced attribute for a node
 188  *
 189  * @param node   The node to set an attribute for.
 190  * @param attr   The name of the attribute to set
 191  * @param xmlns  The namespace of the attribute to ste
 192  * @param prefix The prefix of the attribute to ste
 193  * @param value  The value of the attribute
 194  *
 195  * @since 2.6.0
 196  */
 197 void xmlnode_set_attrib_full(xmlnode *node, const char *attr, const char *xmlns,
 198         const char *prefix, const char *value);
 199
 200 /**
 201  * Gets an attribute from a node.
 202  *
 203  * @param node The node to get an attribute from.
 204  * @param attr The attribute to get.
 205  *
 206  * @return The value of the attribute.
 207  */
 208 const char *xmlnode_get_attrib(const xmlnode *node, const char *attr);
 209
 210 /**
 211  * Gets a namespaced attribute from a node
 212  *
 213  * @param node  The node to get an attribute from.
 214  * @param attr  The attribute to get
 215  * @param xmlns The namespace of the attribute to get
 216  *
 217  * @return The value of the attribute/
 218  */
 219 const char *xmlnode_get_attrib_with_namespace(const xmlnode *node, const char *attr, const char *xmlns);
 220
 221 /**
 222  * Removes an attribute from a node.
 223  *
 224  * @param node The node to remove an attribute from.
 225  * @param attr The attribute to remove.
 226  */
 227 void xmlnode_remove_attrib(xmlnode *node, const char *attr);
 228
 229 /**
 230  * Removes a namespaced attribute from a node
 231  *
 232  * @param node  The node to remove an attribute from
 233  * @param attr  The attribute to remove
 234  * @param xmlns The namespace of the attribute to remove
 235  */
 236 void xmlnode_remove_attrib_with_namespace(xmlnode *node, const char *attr, const char *xmlns);
 237
 238 /**
 239  * Sets the namespace of a node
 240  *
 241  * @param node The node to qualify
 242  * @param xmlns The namespace of the node
 243  */
 244 void xmlnode_set_namespace(xmlnode *node, const char *xmlns);
 245
 246 /**
 247  * Returns the namespace of a node
 248  *
 249  * @param node The node to get the namepsace from
 250  * @return The namespace of this node
 251  */
 252 const char *xmlnode_get_namespace(xmlnode *node);
 253
 254 /**
 255  * Sets the prefix of a node
 256  *
 257  * @param node   The node to qualify
 258  * @param prefix The prefix of the node
 259  */
 260 void xmlnode_set_prefix(xmlnode *node, const char *prefix);
 261
 262 /**
 263  * Returns the prefix of a node
 264  *
 265  * @param node The node to get the prefix from
 266  * @return The prefix of this node
 267  */
 268 const char *xmlnode_get_prefix(const xmlnode *node);
 269
 270 /**
 271  * Gets the parent node.
 272  *
 273  * @param child The child node.
 274  *
 275  * @return The parent or NULL.
 276  *
 277  * @since 2.6.0
 278  */
 279 xmlnode *xmlnode_get_parent(const xmlnode *child);
 280
 281 /**
 282  * Returns the node in a string of xml.
 283  *
 284  * @param node The starting node to output.
 285  * @param len  Address for the size of the string.
 286  *
 287  * @return The node represented as a string.  You must
 288  *         g_free this string when finished using it.
 289  */
 290 char *xmlnode_to_str(const xmlnode *node, int *len);
 291
 292 /**
 293  * Returns the node in a string of human readable xml.
 294  *
 295  * @param node The starting node to output.
 296  * @param len  Address for the size of the string.
 297  *
 298  * @return The node as human readable string including
 299  *         tab and new line characters.  You must
 300  *         g_free this string when finished using it.
 301  */
 302 char *xmlnode_to_formatted_str(const xmlnode *node, int *len);
 303
 304 /**
 305  * Creates a node from a string of XML.  Calling this on the
 306  * root node of an XML document will parse the entire document
 307  * into a tree of nodes, and return the xmlnode of the root.
 308  *
 309  * @param str  The string of xml.
 310  * @param size The size of the string, or -1 if @a str is
 311  *             NUL-terminated.
 312  *
 313  * @return The new node.
 314  */
 315 xmlnode *xmlnode_from_str(const char *str, gssize size);
 316
 317 /**
 318  * Creates a new node from the source node.
 319  *
 320  * @param src The node to copy.
 321  *
 322  * @return A new copy of the src node.
 323  */
 324 xmlnode *xmlnode_copy(const xmlnode *src);
 325
 326 /**
 327  * Frees a node and all of its children.
 328  *
 329  * @param node The node to free.
 330  */
 331 void xmlnode_free(xmlnode *node);
 332
 333 /**
 334  * Creates a node from a XML File.  Calling this on the
 335  * root node of an XML document will parse the entire document
 336  * into a tree of nodes, and return the xmlnode of the root.
 337  *
 338  * @param dir  The directory where the file is located
 339  * @param filename  The filename
 340  * @param description  A description of the file being parsed. Displayed to
 341  *                      the user if the file cannot be read.
 342  * @param process  The subsystem that is calling xmlnode_from_file. Used as
 343  *                      the category for debugging.
 344  *
 345  * @return The new node or NULL if an error occurred.
 346  *
 347  * @since 2.6.0
 348  */
 349 xmlnode *xmlnode_from_file(const char *dir, const char *filename,
 350                            const char *description, const char *process);
 351
 352 #ifdef __cplusplus
 353 }
 354 #endif
 355
 356 #endif /* _PURPLE_XMLNODE_H_ */