Mercurial > pidgin3 / file comparison

comparison: libpurple/xmlnode.h

libpurple/xmlnode.h

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

Mercurial Repository: pidgin3

mercurial