libpurple/xmlnode.h

   1 /* purple
   2  *
   3  * Purple is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  20  */
  21
  22 #ifndef PURPLE_XMLNODE_H
  23 #define PURPLE_XMLNODE_H
  24 /**
  25  * SECTION:xmlnode
  26  * @section_id: libpurple-xmlnode
  27  * @short_description: <filename>xmlnode.h</filename>
  28  * @title: XML DOM functions
  29  */
  30
  31 #include <glib.h>
  32 #include <glib-object.h>
  33
  34 #define PURPLE_TYPE_XMLNODE  (purple_xmlnode_get_type())
  35
  36 /**
  37  * PurpleXmlNodeType:
  38  * @PURPLE_XMLNODE_TYPE_TAG:    Just a tag
  39  * @PURPLE_XMLNODE_TYPE_ATTRIB: Has attributes
  40  * @PURPLE_XMLNODE_TYPE_DATA:   Has data
  41  *
  42  * The valid types for an PurpleXmlNode
  43  */
  44 typedef enum
  45 {
  46         PURPLE_XMLNODE_TYPE_TAG,
  47         PURPLE_XMLNODE_TYPE_ATTRIB,
  48         PURPLE_XMLNODE_TYPE_DATA
  49
  50 } PurpleXmlNodeType;
  51
  52 /**
  53  * PurpleXmlNode:
  54  * @name:          The name of the node.
  55  * @xmlns:         The namespace of the node.
  56  * @type:          The type of the node.
  57  * @data:          The data for the node.
  58  * @data_sz:       The size of the data.
  59  * @parent:        The parent node or %NULL.
  60  * @child:         The child node or %NULL.
  61  * @lastchild:     The last child node or %NULL.
  62  * @next:          The next node or %NULL.
  63  * @prefix:        The namespace prefix if any.
  64  * @namespace_map: The namespace map.
  65  *
  66  * An PurpleXmlNode.
  67  */
  68 typedef struct _PurpleXmlNode PurpleXmlNode;
  69 struct _PurpleXmlNode
  70 {
  71         char *name;
  72         char *xmlns;
  73         PurpleXmlNodeType type;
  74         char *data;
  75         size_t data_sz;
  76         PurpleXmlNode *parent;
  77         PurpleXmlNode *child;
  78         PurpleXmlNode *lastchild;
  79         PurpleXmlNode *next;
  80         char *prefix;
  81         GHashTable *namespace_map;
  82 };
  83
  84 G_BEGIN_DECLS
  85
  86 /**
  87  * purple_xmlnode_get_type:
  88  *
  89  * Returns: The #GType for the #PurpleXmlNode boxed structure.
  90  */
  91 GType purple_xmlnode_get_type(void);
  92
  93 /**
  94  * purple_xmlnode_new:
  95  * @name: The name of the node.
  96  *
  97  * Creates a new PurpleXmlNode.
  98  *
  99  * Returns: The new node.
 100  */
 101 PurpleXmlNode *purple_xmlnode_new(const char *name);
 102
 103 /**
 104  * purple_xmlnode_new_child:
 105  * @parent: The parent node.
 106  * @name:   The name of the child node.
 107  *
 108  * Creates a new PurpleXmlNode child.
 109  *
 110  * Returns: The new child node.
 111  */
 112 PurpleXmlNode *purple_xmlnode_new_child(PurpleXmlNode *parent, const char *name);
 113
 114 /**
 115  * purple_xmlnode_insert_child:
 116  * @parent: The parent node to insert child into.
 117  * @child:  The child node to insert into parent.
 118  *
 119  * Inserts a node into a node as a child.
 120  */
 121 void purple_xmlnode_insert_child(PurpleXmlNode *parent, PurpleXmlNode *child);
 122
 123 /**
 124  * purple_xmlnode_get_child:
 125  * @parent: The parent node.
 126  * @name:   The child's name.
 127  *
 128  * Gets a child node named name.
 129  *
 130  * Returns: The child or NULL.
 131  */
 132 PurpleXmlNode *purple_xmlnode_get_child(const PurpleXmlNode *parent, const char *name);
 133
 134 /**
 135  * purple_xmlnode_get_child_with_namespace:
 136  * @parent: The parent node.
 137  * @name:   The child's name.
 138  * @xmlns:  The namespace.
 139  *
 140  * Gets a child node named name in a namespace.
 141  *
 142  * Returns: The child or NULL.
 143  */
 144 PurpleXmlNode *purple_xmlnode_get_child_with_namespace(const PurpleXmlNode *parent, const char *name, const char *xmlns);
 145
 146 /**
 147  * purple_xmlnode_get_next_twin:
 148  * @node: The node of a twin to find.
 149  *
 150  * Gets the next node with the same name as node.
 151  *
 152  * Returns: The twin of node or NULL.
 153  */
 154 PurpleXmlNode *purple_xmlnode_get_next_twin(PurpleXmlNode *node);
 155
 156 /**
 157  * purple_xmlnode_insert_data:
 158  * @node:   The node to insert data into.
 159  * @data:   The data to insert.
 160  * @size:   The size of the data to insert.  If data is
 161  *               null-terminated you can pass in -1.
 162  *
 163  * Inserts data into a node.
 164  */
 165 void purple_xmlnode_insert_data(PurpleXmlNode *node, const char *data, gssize size);
 166
 167 /**
 168  * purple_xmlnode_get_data:
 169  * @node: The node to get data from.
 170  *
 171  * Gets (escaped) data from a node.
 172  *
 173  * Returns: The data from the node or NULL. This data is in raw escaped format.
 174  *         You must g_free this string when finished using it.
 175  */
 176 char *purple_xmlnode_get_data(const PurpleXmlNode *node);
 177
 178 /**
 179  * purple_xmlnode_get_data_unescaped:
 180  * @node: The node to get data from.
 181  *
 182  * Gets unescaped data from a node.
 183  *
 184  * Returns: The data from the node, in unescaped form.   You must g_free
 185  *         this string when finished using it.
 186  */
 187 char *purple_xmlnode_get_data_unescaped(const PurpleXmlNode *node);
 188
 189 /**
 190  * purple_xmlnode_set_attrib:
 191  * @node:  The node to set an attribute for.
 192  * @attr:  The name of the attribute.
 193  * @value: The value of the attribute.
 194  *
 195  * Sets an attribute for a node.
 196  */
 197 void purple_xmlnode_set_attrib(PurpleXmlNode *node, const char *attr, const char *value);
 198
 199 /**
 200  * purple_xmlnode_set_attrib_full:
 201  * @node:   The node to set an attribute for.
 202  * @attr:   The name of the attribute to set
 203  * @xmlns:  The namespace of the attribute to set
 204  * @prefix: The prefix of the attribute to set
 205  * @value:  The value of the attribute
 206  *
 207  * Sets a namespaced attribute for a node
 208  */
 209 void purple_xmlnode_set_attrib_full(PurpleXmlNode *node, const char *attr, const char *xmlns,
 210                 const char *prefix, const char *value);
 211
 212 /**
 213  * purple_xmlnode_get_attrib:
 214  * @node: The node to get an attribute from.
 215  * @attr: The attribute to get.
 216  *
 217  * Gets an attribute from a node.
 218  *
 219  * Returns: The value of the attribute.
 220  */
 221 const char *purple_xmlnode_get_attrib(const PurpleXmlNode *node, const char *attr);
 222
 223 /**
 224  * purple_xmlnode_get_attrib_with_namespace:
 225  * @node:  The node to get an attribute from.
 226  * @attr:  The attribute to get
 227  * @xmlns: The namespace of the attribute to get
 228  *
 229  * Gets a namespaced attribute from a node
 230  *
 231  * Returns: The value of the attribute/
 232  */
 233 const char *purple_xmlnode_get_attrib_with_namespace(const PurpleXmlNode *node, const char *attr, const char *xmlns);
 234
 235 /**
 236  * purple_xmlnode_remove_attrib:
 237  * @node: The node to remove an attribute from.
 238  * @attr: The attribute to remove.
 239  *
 240  * Removes an attribute from a node.
 241  */
 242 void purple_xmlnode_remove_attrib(PurpleXmlNode *node, const char *attr);
 243
 244 /**
 245  * purple_xmlnode_remove_attrib_with_namespace:
 246  * @node:  The node to remove an attribute from
 247  * @attr:  The attribute to remove
 248  * @xmlns: The namespace of the attribute to remove
 249  *
 250  * Removes a namespaced attribute from a node
 251  */
 252 void purple_xmlnode_remove_attrib_with_namespace(PurpleXmlNode *node, const char *attr, const char *xmlns);
 253
 254 /**
 255  * purple_xmlnode_set_namespace:
 256  * @node: The node to qualify
 257  * @xmlns: The namespace of the node
 258  *
 259  * Sets the namespace of a node
 260  */
 261 void purple_xmlnode_set_namespace(PurpleXmlNode *node, const char *xmlns);
 262
 263 /**
 264  * purple_xmlnode_get_namespace:
 265  * @node: The node to get the namepsace from
 266  *
 267  * Returns the namespace of a node
 268  *
 269  * Returns: The namespace of this node
 270  */
 271 const char *purple_xmlnode_get_namespace(const PurpleXmlNode *node);
 272
 273 /**
 274  * purple_xmlnode_get_default_namespace:
 275  * @node: The node for which to return the default namespace
 276  *
 277  * Returns the current default namespace.  The default
 278  * namespace is the current namespace which applies to child
 279  * elements which are unprefixed and which do not contain their
 280  * own namespace.
 281  *
 282  * For example, given:
 283  * <programlisting>
 284  * &lt;iq type='get' xmlns='jabber:client' xmlns:ns1='http://example.org/ns1'&gt;
 285  *     &lt;ns1:element&gt;&lt;child1/&gt;&lt;/ns1:element&gt;
 286  * &lt;/iq&gt;
 287  * </programlisting>
 288  *
 289  * The default namespace of all nodes (including 'child1') is "jabber:client",
 290  * though the namespace for 'element' is "http://example.org/ns1".
 291  *
 292  * Returns: The default namespace of this node
 293  */
 294 const char *purple_xmlnode_get_default_namespace(const PurpleXmlNode *node);
 295
 296 /**
 297  * purple_xmlnode_get_prefix_namespace:
 298  * @node: The node from which to start the search.
 299  * @prefix: The prefix for which to return the associated namespace.
 300  *
 301  * Returns the defined namespace for a prefix.
 302  *
 303  * Returns: The namespace for this prefix.
 304  */
 305 const char *purple_xmlnode_get_prefix_namespace(const PurpleXmlNode *node, const char *prefix);
 306
 307 /**
 308  * purple_xmlnode_set_prefix:
 309  * @node:   The node to qualify
 310  * @prefix: The prefix of the node
 311  *
 312  * Sets the prefix of a node
 313  */
 314 void purple_xmlnode_set_prefix(PurpleXmlNode *node, const char *prefix);
 315
 316 /**
 317  * purple_xmlnode_get_prefix:
 318  * @node: The node to get the prefix from
 319  *
 320  * Returns the prefix of a node
 321  *
 322  * Returns: The prefix of this node
 323  */
 324 const char *purple_xmlnode_get_prefix(const PurpleXmlNode *node);
 325
 326 /**
 327  * purple_xmlnode_strip_prefixes:
 328  * @node: The node from which to strip prefixes
 329  *
 330  * Remove all element prefixes from an PurpleXmlNode tree.  The prefix's
 331  * namespace is transformed into the default namespace for an element.
 332  *
 333  * Note that this will not necessarily remove all prefixes in use
 334  * (prefixed attributes may still exist), and that this usage may
 335  * break some applications (SOAP / XPath apparently often rely on
 336  * the prefixes having the same name.
 337  */
 338 void purple_xmlnode_strip_prefixes(PurpleXmlNode *node);
 339
 340 /**
 341  * purple_xmlnode_get_parent:
 342  * @child: The child node.
 343  *
 344  * Gets the parent node.
 345  *
 346  * Returns: The parent or NULL.
 347  */
 348 PurpleXmlNode *purple_xmlnode_get_parent(const PurpleXmlNode *child);
 349
 350 /**
 351  * purple_xmlnode_to_str:
 352  * @node: The starting node to output.
 353  * @len:  Address for the size of the string.
 354  *
 355  * Returns the node in a string of xml.
 356  *
 357  * Returns: The node represented as a string.  You must
 358  *         g_free this string when finished using it.
 359  */
 360 char *purple_xmlnode_to_str(const PurpleXmlNode *node, int *len);
 361
 362 /**
 363  * purple_xmlnode_to_formatted_str:
 364  * @node: The starting node to output.
 365  * @len:  Address for the size of the string.
 366  *
 367  * Returns the node in a string of human readable xml.
 368  *
 369  * Returns: The node as human readable string including
 370  *         tab and new line characters.  You must
 371  *         g_free this string when finished using it.
 372  */
 373 char *purple_xmlnode_to_formatted_str(const PurpleXmlNode *node, int *len);
 374
 375 /**
 376  * purple_xmlnode_from_str:
 377  * @str:  The string of xml.
 378  * @size: The size of the string, or -1 if @str is
 379  *             NUL-terminated.
 380  *
 381  * Creates a node from a string of XML.  Calling this on the
 382  * root node of an XML document will parse the entire document
 383  * into a tree of nodes, and return the PurpleXmlNode of the root.
 384  *
 385  * Returns: The new node.
 386  */
 387 PurpleXmlNode *purple_xmlnode_from_str(const char *str, gssize size);
 388
 389 /**
 390  * purple_xmlnode_copy:
 391  * @src: The node to copy.
 392  *
 393  * Creates a new node from the source node.
 394  *
 395  * Returns: A new copy of the src node.
 396  */
 397 PurpleXmlNode *purple_xmlnode_copy(const PurpleXmlNode *src);
 398
 399 /**
 400  * purple_xmlnode_free:
 401  * @node: The node to free.
 402  *
 403  * Frees a node and all of its children.
 404  */
 405 void purple_xmlnode_free(PurpleXmlNode *node);
 406
 407 /**
 408  * purple_xmlnode_from_file:
 409  * @dir:  The directory where the file is located
 410  * @filename:  The filename
 411  * @description:  A description of the file being parsed. Displayed to
 412  *        the user if the file cannot be read.
 413  * @process:  The subsystem that is calling purple_xmlnode_from_file. Used as
 414  *        the category for debugging.
 415  *
 416  * Creates a node from a XML File.  Calling this on the
 417  * root node of an XML document will parse the entire document
 418  * into a tree of nodes, and return the PurpleXmlNode of the root.
 419  *
 420  * Returns: The new node or NULL if an error occurred.
 421  */
 422 PurpleXmlNode *purple_xmlnode_from_file(const char *dir, const char *filename,
 423                 const char *description, const char *process);
 424
 425 G_END_DECLS
 426
 427 #endif /* PURPLE_XMLNODE_H */