Frameworks/libpurple.framework/Versions/2.10.12r8d2874a79747/Headers/xmlnode.h
branchadium-1.5.11-merge
changeset 6013 f8d0dc659e3f
parent 5941 307f53385811
parent 6012 200a01709ba4
child 6014 fcb71cb71a3d
child 6015 2b01cc935b7c
equal deleted inserted replaced
5941:307f53385811 6013:f8d0dc659e3f
     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(const xmlnode *node);
       
   253 
       
   254 /**
       
   255  * Returns the current default namespace.  The default
       
   256  * namespace is the current namespace which applies to child
       
   257  * elements which are unprefixed and which do not contain their
       
   258  * own namespace.
       
   259  *
       
   260  * For example, given:
       
   261  * <iq type='get' xmlns='jabber:client' xmlns:ns1='http://example.org/ns1'>
       
   262  *     <ns1:element><child1/></ns1:element>
       
   263  * </iq>
       
   264  *
       
   265  * The default namespace of all nodes (including 'child1') is "jabber:client",
       
   266  * though the namespace for 'element' is "http://example.org/ns1".
       
   267  *
       
   268  * @param node The node for which to return the default namespace
       
   269  * @return The default namespace of this node
       
   270  */
       
   271 const char *xmlnode_get_default_namespace(const xmlnode *node);
       
   272 
       
   273 /**
       
   274  * Returns the defined namespace for a prefix.
       
   275  *
       
   276  * @param node The node from which to start the search.
       
   277  * @param prefix The prefix for which to return the associated namespace.
       
   278  * @return The namespace for this prefix.
       
   279  */
       
   280 const char *xmlnode_get_prefix_namespace(const xmlnode *node, const char *prefix);
       
   281 
       
   282 /**
       
   283  * Sets the prefix of a node
       
   284  *
       
   285  * @param node   The node to qualify
       
   286  * @param prefix The prefix of the node
       
   287  */
       
   288 void xmlnode_set_prefix(xmlnode *node, const char *prefix);
       
   289 
       
   290 /**
       
   291  * Returns the prefix of a node
       
   292  *
       
   293  * @param node The node to get the prefix from
       
   294  * @return The prefix of this node
       
   295  */
       
   296 const char *xmlnode_get_prefix(const xmlnode *node);
       
   297 
       
   298 /**
       
   299  * Remove all element prefixes from an xmlnode tree.  The prefix's
       
   300  * namespace is transformed into the default namespace for an element.
       
   301  *
       
   302  * Note that this will not necessarily remove all prefixes in use
       
   303  * (prefixed attributes may still exist), and that this usage may
       
   304  * break some applications (SOAP / XPath apparently often rely on
       
   305  * the prefixes having the same name.
       
   306  *
       
   307  * @param node The node from which to strip prefixes
       
   308  */
       
   309 void xmlnode_strip_prefixes(xmlnode *node);
       
   310 
       
   311 /**
       
   312  * Gets the parent node.
       
   313  *
       
   314  * @param child The child node.
       
   315  *
       
   316  * @return The parent or NULL.
       
   317  *
       
   318  * @since 2.6.0
       
   319  */
       
   320 xmlnode *xmlnode_get_parent(const xmlnode *child);
       
   321 
       
   322 /**
       
   323  * Returns the node in a string of xml.
       
   324  *
       
   325  * @param node The starting node to output.
       
   326  * @param len  Address for the size of the string.
       
   327  *
       
   328  * @return The node represented as a string.  You must
       
   329  *         g_free this string when finished using it.
       
   330  */
       
   331 char *xmlnode_to_str(const xmlnode *node, int *len);
       
   332 
       
   333 /**
       
   334  * Returns the node in a string of human readable xml.
       
   335  *
       
   336  * @param node The starting node to output.
       
   337  * @param len  Address for the size of the string.
       
   338  *
       
   339  * @return The node as human readable string including
       
   340  *         tab and new line characters.  You must
       
   341  *         g_free this string when finished using it.
       
   342  */
       
   343 char *xmlnode_to_formatted_str(const xmlnode *node, int *len);
       
   344 
       
   345 /**
       
   346  * Creates a node from a string of XML.  Calling this on the
       
   347  * root node of an XML document will parse the entire document
       
   348  * into a tree of nodes, and return the xmlnode of the root.
       
   349  *
       
   350  * @param str  The string of xml.
       
   351  * @param size The size of the string, or -1 if @a str is
       
   352  *             NUL-terminated.
       
   353  *
       
   354  * @return The new node.
       
   355  */
       
   356 xmlnode *xmlnode_from_str(const char *str, gssize size);
       
   357 
       
   358 /**
       
   359  * Creates a new node from the source node.
       
   360  *
       
   361  * @param src The node to copy.
       
   362  *
       
   363  * @return A new copy of the src node.
       
   364  */
       
   365 xmlnode *xmlnode_copy(const xmlnode *src);
       
   366 
       
   367 /**
       
   368  * Frees a node and all of its children.
       
   369  *
       
   370  * @param node The node to free.
       
   371  */
       
   372 void xmlnode_free(xmlnode *node);
       
   373 
       
   374 /**
       
   375  * Creates a node from a XML File.  Calling this on the
       
   376  * root node of an XML document will parse the entire document
       
   377  * into a tree of nodes, and return the xmlnode of the root.
       
   378  *
       
   379  * @param dir  The directory where the file is located
       
   380  * @param filename  The filename
       
   381  * @param description  A description of the file being parsed. Displayed to
       
   382  * 			the user if the file cannot be read.
       
   383  * @param process  The subsystem that is calling xmlnode_from_file. Used as
       
   384  * 			the category for debugging.
       
   385  *
       
   386  * @return The new node or NULL if an error occurred.
       
   387  *
       
   388  * @since 2.6.0
       
   389  */
       
   390 xmlnode *xmlnode_from_file(const char *dir, const char *filename,
       
   391 			   const char *description, const char *process);
       
   392 
       
   393 #ifdef __cplusplus
       
   394 }
       
   395 #endif
       
   396 
       
   397 #endif /* _PURPLE_XMLNODE_H_ */