summaryrefslogtreecommitdiff
path: root/libpurple/xmlnode.h
blob: bfc41f24031b09feef9251195148c0efd887a234 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
/**
 * @file xmlnode.h XML DOM functions
 * @ingroup core
 */

/* purple
 *
 * Purple is the legal property of its developers, whose names are too numerous
 * to list here.  Please refer to the COPYRIGHT file distributed with this
 * source distribution.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
 */
#ifndef _PURPLE_XMLNODE_H_
#define _PURPLE_XMLNODE_H_

#include <glib.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * The valid types for an xmlnode
 */
typedef enum _XMLNodeType
{
	XMLNODE_TYPE_TAG,		/**< Just a tag */
	XMLNODE_TYPE_ATTRIB,		/**< Has attributes */
	XMLNODE_TYPE_DATA		/**< Has data */
} XMLNodeType;

/**
 * An xmlnode.
 */
typedef struct _xmlnode xmlnode;
struct _xmlnode
{
	char *name;			/**< The name of the node. */
	char *xmlns;		/**< The namespace of the node */
	XMLNodeType type;		/**< The type of the node. */
	char *data;			/**< The data for the node. */
	size_t data_sz;			/**< The size of the data. */
	struct _xmlnode *parent;	/**< The parent node or @c NULL.*/
	struct _xmlnode *child;		/**< The child node or @c NULL.*/
	struct _xmlnode *lastchild;	/**< The last child node or @c NULL.*/
	struct _xmlnode *next;		/**< The next node or @c NULL. */
	char *prefix;               /**< The namespace prefix if any. */
	GHashTable *namespace_map;  /**< The namespace map. */
};

/**
 * Creates a new xmlnode.
 *
 * @param name The name of the node.
 *
 * @return The new node.
 */
xmlnode *xmlnode_new(const char *name);

/**
 * Creates a new xmlnode child.
 *
 * @param parent The parent node.
 * @param name   The name of the child node.
 *
 * @return The new child node.
 */
xmlnode *xmlnode_new_child(xmlnode *parent, const char *name);

/**
 * Inserts a node into a node as a child.
 *
 * @param parent The parent node to insert child into.
 * @param child  The child node to insert into parent.
 */
void xmlnode_insert_child(xmlnode *parent, xmlnode *child);

/**
 * Gets a child node named name.
 *
 * @param parent The parent node.
 * @param name   The child's name.
 *
 * @return The child or NULL.
 */
xmlnode *xmlnode_get_child(const xmlnode *parent, const char *name);

/**
 * Gets a child node named name in a namespace.
 *
 * @param parent The parent node.
 * @param name   The child's name.
 * @param xmlns  The namespace.
 *
 * @return The child or NULL.
 */
xmlnode *xmlnode_get_child_with_namespace(const xmlnode *parent, const char *name, const char *xmlns);

/**
 * Gets the next node with the same name as node.
 *
 * @param node The node of a twin to find.
 *
 * @return The twin of node or NULL.
 */
xmlnode *xmlnode_get_next_twin(xmlnode *node);

/**
 * Inserts data into a node.
 *
 * @param node   The node to insert data into.
 * @param data   The data to insert.
 * @param size   The size of the data to insert.  If data is
 *               null-terminated you can pass in -1.
 */
void xmlnode_insert_data(xmlnode *node, const char *data, gssize size);

/**
 * Gets (escaped) data from a node.
 *
 * @param node The node to get data from.
 *
 * @return The data from the node or NULL. This data is in raw escaped format.
 *         You must g_free this string when finished using it.
 */
char *xmlnode_get_data(xmlnode *node);

/**
 * Gets unescaped data from a node.
 *
 * @param node The node to get data from.
 *
 * @return The data from the node, in unescaped form.   You must g_free
 *         this string when finished using it.
 */
char *xmlnode_get_data_unescaped(xmlnode *node);

/**
 * Sets an attribute for a node.
 *
 * @param node  The node to set an attribute for.
 * @param attr  The name of the attribute.
 * @param value The value of the attribute.
 */
void xmlnode_set_attrib(xmlnode *node, const char *attr, const char *value);

#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_XMLNODE_C_)
/**
 * Sets a prefixed attribute for a node
 *
 * @param node   The node to set an attribute for.
 * @param attr   The name of the attribute to set
 * @param prefix The prefix of the attribute to ste
 * @param value  The value of the attribute
 *
 * @deprecated Use xmlnode_set_attrib_full instead.
 */
void xmlnode_set_attrib_with_prefix(xmlnode *node, const char *attr, const char *prefix, const char *value);

/**
 * Sets a namespaced attribute for a node
 *
 * @param node  The node to set an attribute for.
 * @param attr  The name of the attribute to set
 * @param xmlns The namespace of the attribute to ste
 * @param value The value of the attribute
 *
 * @deprecated Use xmlnode_set_attrib_full instead.
 */
void xmlnode_set_attrib_with_namespace(xmlnode *node, const char *attr, const char *xmlns, const char *value);
#endif /* PURPLE_DISABLE_DEPRECATED */

/**
 * Sets a namespaced attribute for a node
 *
 * @param node   The node to set an attribute for.
 * @param attr   The name of the attribute to set
 * @param xmlns  The namespace of the attribute to ste
 * @param prefix The prefix of the attribute to ste
 * @param value  The value of the attribute
 *
 * @since 2.6.0
 */
void xmlnode_set_attrib_full(xmlnode *node, const char *attr, const char *xmlns,
	const char *prefix, const char *value);

/**
 * Gets an attribute from a node.
 *
 * @param node The node to get an attribute from.
 * @param attr The attribute to get.
 *
 * @return The value of the attribute.
 */
const char *xmlnode_get_attrib(xmlnode *node, const char *attr);

/**
 * Gets a namespaced attribute from a node
 *
 * @param node  The node to get an attribute from.
 * @param attr  The attribute to get
 * @param xmlns The namespace of the attribute to get
 *
 * @return The value of the attribute/
 */
const char *xmlnode_get_attrib_with_namespace(xmlnode *node, const char *attr, const char *xmlns);

/**
 * Removes an attribute from a node.
 *
 * @param node The node to remove an attribute from.
 * @param attr The attribute to remove.
 */
void xmlnode_remove_attrib(xmlnode *node, const char *attr);

/**
 * Removes a namespaced attribute from a node
 *
 * @param node  The node to remove an attribute from
 * @param attr  The attribute to remove
 * @param xmlns The namespace of the attribute to remove
 */
void xmlnode_remove_attrib_with_namespace(xmlnode *node, const char *attr, const char *xmlns);

/**
 * Sets the namespace of a node
 *
 * @param node The node to qualify
 * @param xmlns The namespace of the node
 */
void xmlnode_set_namespace(xmlnode *node, const char *xmlns);

/**
 * Returns the namespace of a node
 *
 * @param node The node to get the namepsace from
 * @return The namespace of this node
 */
const char *xmlnode_get_namespace(xmlnode *node);

/**
 * Sets the prefix of a node
 *
 * @param node   The node to qualify
 * @param prefix The prefix of the node
 */
void xmlnode_set_prefix(xmlnode *node, const char *prefix);

/**
 * Returns the prefix of a node
 *
 * @param node The node to get the prefix from
 * @return The prefix of this node
 */
const char *xmlnode_get_prefix(const xmlnode *node);

/**
 * Returns the node in a string of xml.
 *
 * @param node The starting node to output.
 * @param len  Address for the size of the string.
 *
 * @return The node represented as a string.  You must
 *         g_free this string when finished using it.
 */
char *xmlnode_to_str(const xmlnode *node, int *len);

/**
 * Returns the node in a string of human readable xml.
 *
 * @param node The starting node to output.
 * @param len  Address for the size of the string.
 *
 * @return The node as human readable string including
 *         tab and new line characters.  You must
 *         g_free this string when finished using it.
 */
char *xmlnode_to_formatted_str(const xmlnode *node, int *len);

/**
 * Creates a node from a string of XML.  Calling this on the
 * root node of an XML document will parse the entire document
 * into a tree of nodes, and return the xmlnode of the root.
 *
 * @param str  The string of xml.
 * @param size The size of the string, or -1 if @a str is
 *             NUL-terminated.
 *
 * @return The new node.
 */
xmlnode *xmlnode_from_str(const char *str, gssize size);

/**
 * Creates a new node from the source node.
 *
 * @param src The node to copy.
 *
 * @return A new copy of the src node.
 */
xmlnode *xmlnode_copy(const xmlnode *src);

/**
 * Frees a node and all of its children.
 *
 * @param node The node to free.
 */
void xmlnode_free(xmlnode *node);

/**
 * Creates a node from a XML File.  Calling this on the
 * root node of an XML document will parse the entire document
 * into a tree of nodes, and return the xmlnode of the root.
 *
 * @param str  The string of xml.
 * @param description  The description of the file being parsed
 * @process  The utility that is calling xmlnode_from_file
 *
 * @return The new node.
 *
 * @since 2.6.0
 */
xmlnode *xmlnode_from_file(const char *dir, const char *filename,
			   const char *description, const char *process);

#ifdef __cplusplus
}
#endif

#endif /* _PURPLE_XMLNODE_H_ */