src/core/sipe-xml.h

   1 /**
   2  * @file sipe-xml.h
   3  *
   4  * pidgin-sipe
   5  *
   6  * Copyright (C) 2010-11 SIPE Project <http://sipe.sourceforge.net/>
   7  *
   8  * This program is free software; you can redistribute it and/or modify
   9  * it under the terms of the GNU General Public License as published by
  10  * the Free Software Foundation; either version 2 of the License, or
  11  * (at your option) any later version.
  12  *
  13  * This program is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  * GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  21  */
  22
  23 typedef struct _sipe_xml sipe_xml;
  24
  25 /**
  26  * Parse XML from a string.
  27  *
  28  * @param string String with the XML to be parsed.
  29  * @param length Length of the string.
  30  *
  31  * @return Parsed XML information. Must be @c sipe_xml_free()'d.
  32  */
  33 sipe_xml *sipe_xml_parse(const gchar *string, gsize length);
  34
  35 /**
  36  * Free XML information.
  37  *
  38  * @param string XML information to be freed.
  39  */
  40 void sipe_xml_free(sipe_xml *xml);
  41
  42 /**
  43  * Convert XML information to string.
  44  *
  45  * @param xml XML information.
  46  *
  47  * @return XML converted to a string. Must be @c g_free()'d.
  48  */
  49 gchar *sipe_xml_stringify(const sipe_xml *xml);
  50
  51 /**
  52  * Gets a child node named name.
  53  *
  54  * @param parent The parent node.
  55  * @param name   relative XPATH of the child (a, a/b, a/b/c, etc.).
  56  *
  57  * @return The child or @c NULL. Never try to @c sipe_xml_free() it!
  58  */
  59 const sipe_xml *sipe_xml_child(const sipe_xml *parent, const gchar *name);
  60
  61 /**
  62  * Gets the next node with the same name as node.
  63  *
  64  * @param node The node of a twin to find.
  65  *
  66  * @return The twin of node or @c NULL.
  67  */
  68 const sipe_xml *sipe_xml_twin(const sipe_xml *node);
  69
  70 /**
  71  * Gets the name from the current XML node.
  72  *
  73  * @param node The node to get the name from.
  74  *
  75  * @return The name of the node
  76  */
  77 const gchar *sipe_xml_name(const sipe_xml *node);
  78
  79 /**
  80  * Gets an attribute from the current XML node.
  81  *
  82  * @param node The node to get an attribute from.
  83  * @param attr The attribute to get.
  84  *
  85  * @return The value of the attribute or @c NULL.
  86  */
  87 const gchar *sipe_xml_attribute(const sipe_xml *node, const gchar *attr);
  88
  89 /**
  90  * Gets an attribute from the current XML node and convert it to an
  91  * unsigned integer.
  92  *
  93  * @param node     The node to get an attribute from.
  94  * @param attr     The attribute to get.
  95  * @param fallback Default value if the attribute doesn't exist.
  96  *
  97  * @return Attribute value converted to an integer or the fallback value.
  98  */
  99 guint sipe_xml_int_attribute(const sipe_xml *node, const gchar *attr,
 100                              guint fallback);
 101
 102 /**
 103  * Gets escaped data from the current XML node.
 104  *
 105  * @param node The node to get data from.
 106  *
 107  * @return The data from the node or @c NULL. Must be @c g_free()'d.
 108  */
 109 gchar *sipe_xml_data(const sipe_xml *node);
 110
 111 /**
 112  * For debugging while writing XML processing code.
 113  * NOTE: the code for this function is flagged out by default!
 114  *
 115  * @param node The node to start dumping from
 116  * @param path The path to this node (can be NULL)
 117  */
 118 void sipe_xml_dump(const sipe_xml *node, const gchar *path);
 119
 120 /* Other XML convenience functions */
 121
 122 /**
 123  * Apply "Exclusive XML Canonicalization" to a XML string
 124  * See also http://www.w3.org/TR/xml-exc-c14n/
 125  *
 126  * @param string String with the XML to be canonicalized.
 127  *
 128  * @return canonicalized XML string. Must be @c g_free()'d.
 129  */
 130 gchar *sipe_xml_exc_c14n(const gchar *string);
 131
 132 /**
 133  * Extracts raw data between a pair of XML tags.
 134  *
 135  * @param xml XML document
 136  * @param tag XML tag enclosing the data
 137  * @param include_tag whether the enclosing tags should be included in the result
 138  *
 139  * @return a first substring from the XML document enclosed by @c tag.
 140  * Must be @c g_free()'d.
 141  */
 142 gchar *sipe_xml_extract_raw(const gchar *xml, const gchar *tag,
 143                             gboolean include_tag);