Mercurial > pidgin3 / file comparison

comparison: libpurple/xmlnode.h

libpurple/xmlnode.h

branch
gtkdoc-conversion
changeset 35393
00f876b129bc
parent 34935
686fa55b0deb
child 35403
9282701d7aa9
child 37035
e85ed7f4d6e3
equal deleted inserted replaced
35392:cc123f0d84af 35393:00f876b129bc
50 char *name; /**< The name of the node. */ 50 char *name; /**< The name of the node. */
51 char *xmlns; /**< The namespace of the node */ 51 char *xmlns; /**< The namespace of the node */
52 PurpleXmlNodeType type; /**< The type of the node. */ 52 PurpleXmlNodeType type; /**< The type of the node. */
53 char *data; /**< The data for the node. */ 53 char *data; /**< The data for the node. */
54 size_t data_sz; /**< The size of the data. */ 54 size_t data_sz; /**< The size of the data. */
55 PurpleXmlNode *parent; /**< The parent node or @c NULL.*/ 55 PurpleXmlNode *parent; /**< The parent node or %NULL.*/
56 PurpleXmlNode *child; /**< The child node or @c NULL.*/ 56 PurpleXmlNode *child; /**< The child node or %NULL.*/
57 PurpleXmlNode *lastchild; /**< The last child node or @c NULL.*/ 57 PurpleXmlNode *lastchild; /**< The last child node or %NULL.*/
58 PurpleXmlNode *next; /**< The next node or @c NULL. */ 58 PurpleXmlNode *next; /**< The next node or %NULL. */
59 char *prefix; /**< The namespace prefix if any. */ 59 char *prefix; /**< The namespace prefix if any. */
60 GHashTable *namespace_map; /**< The namespace map. */ 60 GHashTable *namespace_map; /**< The namespace map. */
61 }; 61 };
62 62
63 G_BEGIN_DECLS 63 G_BEGIN_DECLS
68 GType purple_xmlnode_get_type(void); 68 GType purple_xmlnode_get_type(void);
69 69
70 /** 70 /**
71 * Creates a new PurpleXmlNode. 71 * Creates a new PurpleXmlNode.
72 * 72 *
73 * @param name The name of the node. 73 * @name: The name of the node.
74 * 74 *
75 * @return The new node. 75 * Returns: The new node.
76 */ 76 */
77 PurpleXmlNode *purple_xmlnode_new(const char *name); 77 PurpleXmlNode *purple_xmlnode_new(const char *name);
78 78
79 /** 79 /**
80 * Creates a new PurpleXmlNode child. 80 * Creates a new PurpleXmlNode child.
81 * 81 *
82 * @param parent The parent node. 82 * @parent: The parent node.
83 * @param name The name of the child node. 83 * @name: The name of the child node.
84 * 84 *
85 * @return The new child node. 85 * Returns: The new child node.
86 */ 86 */
87 PurpleXmlNode *purple_xmlnode_new_child(PurpleXmlNode *parent, const char *name); 87 PurpleXmlNode *purple_xmlnode_new_child(PurpleXmlNode *parent, const char *name);
88 88
89 /** 89 /**
90 * Inserts a node into a node as a child. 90 * Inserts a node into a node as a child.
91 * 91 *
92 * @param parent The parent node to insert child into. 92 * @parent: The parent node to insert child into.
93 * @param child The child node to insert into parent. 93 * @child: The child node to insert into parent.
94 */ 94 */
95 void purple_xmlnode_insert_child(PurpleXmlNode *parent, PurpleXmlNode *child); 95 void purple_xmlnode_insert_child(PurpleXmlNode *parent, PurpleXmlNode *child);
96 96
97 /** 97 /**
98 * Gets a child node named name. 98 * Gets a child node named name.
99 * 99 *
100 * @param parent The parent node. 100 * @parent: The parent node.
101 * @param name The child's name. 101 * @name: The child's name.
102 * 102 *
103 * @return The child or NULL. 103 * Returns: The child or NULL.
104 */ 104 */
105 PurpleXmlNode *purple_xmlnode_get_child(const PurpleXmlNode *parent, const char *name); 105 PurpleXmlNode *purple_xmlnode_get_child(const PurpleXmlNode *parent, const char *name);
106 106
107 /** 107 /**
108 * Gets a child node named name in a namespace. 108 * Gets a child node named name in a namespace.
109 * 109 *
110 * @param parent The parent node. 110 * @parent: The parent node.
111 * @param name The child's name. 111 * @name: The child's name.
112 * @param xmlns The namespace. 112 * @xmlns: The namespace.
113 * 113 *
114 * @return The child or NULL. 114 * Returns: The child or NULL.
115 */ 115 */
116 PurpleXmlNode *purple_xmlnode_get_child_with_namespace(const PurpleXmlNode *parent, const char *name, const char *xmlns); 116 PurpleXmlNode *purple_xmlnode_get_child_with_namespace(const PurpleXmlNode *parent, const char *name, const char *xmlns);
117 117
118 /** 118 /**
119 * Gets the next node with the same name as node. 119 * Gets the next node with the same name as node.
120 * 120 *
121 * @param node The node of a twin to find. 121 * @node: The node of a twin to find.
122 * 122 *
123 * @return The twin of node or NULL. 123 * Returns: The twin of node or NULL.
124 */ 124 */
125 PurpleXmlNode *purple_xmlnode_get_next_twin(PurpleXmlNode *node); 125 PurpleXmlNode *purple_xmlnode_get_next_twin(PurpleXmlNode *node);
126 126
127 /** 127 /**
128 * Inserts data into a node. 128 * Inserts data into a node.
129 * 129 *
130 * @param node The node to insert data into. 130 * @node: The node to insert data into.
131 * @param data The data to insert. 131 * @data: The data to insert.
132 * @param size The size of the data to insert. If data is 132 * @size: The size of the data to insert. If data is
133 * null-terminated you can pass in -1. 133 * null-terminated you can pass in -1.
134 */ 134 */
135 void purple_xmlnode_insert_data(PurpleXmlNode *node, const char *data, gssize size); 135 void purple_xmlnode_insert_data(PurpleXmlNode *node, const char *data, gssize size);
136 136
137 /** 137 /**
138 * Gets (escaped) data from a node. 138 * Gets (escaped) data from a node.
139 * 139 *
140 * @param node The node to get data from. 140 * @node: The node to get data from.
141 * 141 *
142 * @return The data from the node or NULL. This data is in raw escaped format. 142 * 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. 143 * You must g_free this string when finished using it.
144 */ 144 */
145 char *purple_xmlnode_get_data(const PurpleXmlNode *node); 145 char *purple_xmlnode_get_data(const PurpleXmlNode *node);
146 146
147 /** 147 /**
148 * Gets unescaped data from a node. 148 * Gets unescaped data from a node.
149 * 149 *
150 * @param node The node to get data from. 150 * @node: The node to get data from.
151 * 151 *
152 * @return The data from the node, in unescaped form. You must g_free 152 * Returns: The data from the node, in unescaped form. You must g_free
153 * this string when finished using it. 153 * this string when finished using it.
154 */ 154 */
155 char *purple_xmlnode_get_data_unescaped(const PurpleXmlNode *node); 155 char *purple_xmlnode_get_data_unescaped(const PurpleXmlNode *node);
156 156
157 /** 157 /**
158 * Sets an attribute for a node. 158 * Sets an attribute for a node.
159 * 159 *
160 * @param node The node to set an attribute for. 160 * @node: The node to set an attribute for.
161 * @param attr The name of the attribute. 161 * @attr: The name of the attribute.
162 * @param value The value of the attribute. 162 * @value: The value of the attribute.
163 */ 163 */
164 void purple_xmlnode_set_attrib(PurpleXmlNode *node, const char *attr, const char *value); 164 void purple_xmlnode_set_attrib(PurpleXmlNode *node, const char *attr, const char *value);
165 165
166 /** 166 /**
167 * Sets a namespaced attribute for a node 167 * Sets a namespaced attribute for a node
168 * 168 *
169 * @param node The node to set an attribute for. 169 * @node: The node to set an attribute for.
170 * @param attr The name of the attribute to set 170 * @attr: The name of the attribute to set
171 * @param xmlns The namespace of the attribute to set 171 * @xmlns: The namespace of the attribute to set
172 * @param prefix The prefix of the attribute to set 172 * @prefix: The prefix of the attribute to set
173 * @param value The value of the attribute 173 * @value: The value of the attribute
174 */ 174 */
175 void purple_xmlnode_set_attrib_full(PurpleXmlNode *node, const char *attr, const char *xmlns, 175 void purple_xmlnode_set_attrib_full(PurpleXmlNode *node, const char *attr, const char *xmlns,
176 const char *prefix, const char *value); 176 const char *prefix, const char *value);
177 177
178 /** 178 /**
179 * Gets an attribute from a node. 179 * Gets an attribute from a node.
180 * 180 *
181 * @param node The node to get an attribute from. 181 * @node: The node to get an attribute from.
182 * @param attr The attribute to get. 182 * @attr: The attribute to get.
183 * 183 *
184 * @return The value of the attribute. 184 * Returns: The value of the attribute.
185 */ 185 */
186 const char *purple_xmlnode_get_attrib(const PurpleXmlNode *node, const char *attr); 186 const char *purple_xmlnode_get_attrib(const PurpleXmlNode *node, const char *attr);
187 187
188 /** 188 /**
189 * Gets a namespaced attribute from a node 189 * Gets a namespaced attribute from a node
190 * 190 *
191 * @param node The node to get an attribute from. 191 * @node: The node to get an attribute from.
192 * @param attr The attribute to get 192 * @attr: The attribute to get
193 * @param xmlns The namespace of the attribute to get 193 * @xmlns: The namespace of the attribute to get
194 * 194 *
195 * @return The value of the attribute/ 195 * Returns: The value of the attribute/
196 */ 196 */
197 const char *purple_xmlnode_get_attrib_with_namespace(const PurpleXmlNode *node, const char *attr, const char *xmlns); 197 const char *purple_xmlnode_get_attrib_with_namespace(const PurpleXmlNode *node, const char *attr, const char *xmlns);
198 198
199 /** 199 /**
200 * Removes an attribute from a node. 200 * Removes an attribute from a node.
201 * 201 *
202 * @param node The node to remove an attribute from. 202 * @node: The node to remove an attribute from.
203 * @param attr The attribute to remove. 203 * @attr: The attribute to remove.
204 */ 204 */
205 void purple_xmlnode_remove_attrib(PurpleXmlNode *node, const char *attr); 205 void purple_xmlnode_remove_attrib(PurpleXmlNode *node, const char *attr);
206 206
207 /** 207 /**
208 * Removes a namespaced attribute from a node 208 * Removes a namespaced attribute from a node
209 * 209 *
210 * @param node The node to remove an attribute from 210 * @node: The node to remove an attribute from
211 * @param attr The attribute to remove 211 * @attr: The attribute to remove
212 * @param xmlns The namespace of the attribute to remove 212 * @xmlns: The namespace of the attribute to remove
213 */ 213 */
214 void purple_xmlnode_remove_attrib_with_namespace(PurpleXmlNode *node, const char *attr, const char *xmlns); 214 void purple_xmlnode_remove_attrib_with_namespace(PurpleXmlNode *node, const char *attr, const char *xmlns);
215 215
216 /** 216 /**
217 * Sets the namespace of a node 217 * Sets the namespace of a node
218 * 218 *
219 * @param node The node to qualify 219 * @node: The node to qualify
220 * @param xmlns The namespace of the node 220 * @xmlns: The namespace of the node
221 */ 221 */
222 void purple_xmlnode_set_namespace(PurpleXmlNode *node, const char *xmlns); 222 void purple_xmlnode_set_namespace(PurpleXmlNode *node, const char *xmlns);
223 223
224 /** 224 /**
225 * Returns the namespace of a node 225 * Returns the namespace of a node
226 * 226 *
227 * @param node The node to get the namepsace from 227 * @node: The node to get the namepsace from
228 * @return The namespace of this node 228 * Returns: The namespace of this node
229 */ 229 */
230 const char *purple_xmlnode_get_namespace(const PurpleXmlNode *node); 230 const char *purple_xmlnode_get_namespace(const PurpleXmlNode *node);
231 231
232 /** 232 /**
233 * Returns the current default namespace. The default 233 * Returns the current default namespace. The default
243 * \endverbatim 243 * \endverbatim
244 * 244 *
245 * The default namespace of all nodes (including 'child1') is "jabber:client", 245 * The default namespace of all nodes (including 'child1') is "jabber:client",
246 * though the namespace for 'element' is "http://example.org/ns1". 246 * though the namespace for 'element' is "http://example.org/ns1".
247 * 247 *
248 * @param node The node for which to return the default namespace 248 * @node: The node for which to return the default namespace
249 * @return The default namespace of this node 249 * Returns: The default namespace of this node
250 */ 250 */
251 const char *purple_xmlnode_get_default_namespace(const PurpleXmlNode *node); 251 const char *purple_xmlnode_get_default_namespace(const PurpleXmlNode *node);
252 252
253 /** 253 /**
254 * Returns the defined namespace for a prefix. 254 * Returns the defined namespace for a prefix.
255 * 255 *
256 * @param node The node from which to start the search. 256 * @node: The node from which to start the search.
257 * @param prefix The prefix for which to return the associated namespace. 257 * @prefix: The prefix for which to return the associated namespace.
258 * @return The namespace for this prefix. 258 * Returns: The namespace for this prefix.
259 */ 259 */
260 const char *purple_xmlnode_get_prefix_namespace(const PurpleXmlNode *node, const char *prefix); 260 const char *purple_xmlnode_get_prefix_namespace(const PurpleXmlNode *node, const char *prefix);
261 261
262 /** 262 /**
263 * Sets the prefix of a node 263 * Sets the prefix of a node
264 * 264 *
265 * @param node The node to qualify 265 * @node: The node to qualify
266 * @param prefix The prefix of the node 266 * @prefix: The prefix of the node
267 */ 267 */
268 void purple_xmlnode_set_prefix(PurpleXmlNode *node, const char *prefix); 268 void purple_xmlnode_set_prefix(PurpleXmlNode *node, const char *prefix);
269 269
270 /** 270 /**
271 * Returns the prefix of a node 271 * Returns the prefix of a node
272 * 272 *
273 * @param node The node to get the prefix from 273 * @node: The node to get the prefix from
274 * @return The prefix of this node 274 * Returns: The prefix of this node
275 */ 275 */
276 const char *purple_xmlnode_get_prefix(const PurpleXmlNode *node); 276 const char *purple_xmlnode_get_prefix(const PurpleXmlNode *node);
277 277
278 /** 278 /**
279 * Remove all element prefixes from an PurpleXmlNode tree. The prefix's 279 * Remove all element prefixes from an PurpleXmlNode tree. The prefix's
282 * Note that this will not necessarily remove all prefixes in use 282 * Note that this will not necessarily remove all prefixes in use
283 * (prefixed attributes may still exist), and that this usage may 283 * (prefixed attributes may still exist), and that this usage may
284 * break some applications (SOAP / XPath apparently often rely on 284 * break some applications (SOAP / XPath apparently often rely on
285 * the prefixes having the same name. 285 * the prefixes having the same name.
286 * 286 *
287 * @param node The node from which to strip prefixes 287 * @node: The node from which to strip prefixes
288 */ 288 */
289 void purple_xmlnode_strip_prefixes(PurpleXmlNode *node); 289 void purple_xmlnode_strip_prefixes(PurpleXmlNode *node);
290 290
291 /** 291 /**
292 * Gets the parent node. 292 * Gets the parent node.
293 * 293 *
294 * @param child The child node. 294 * @child: The child node.
295 * 295 *
296 * @return The parent or NULL. 296 * Returns: The parent or NULL.
297 */ 297 */
298 PurpleXmlNode *purple_xmlnode_get_parent(const PurpleXmlNode *child); 298 PurpleXmlNode *purple_xmlnode_get_parent(const PurpleXmlNode *child);
299 299
300 /** 300 /**
301 * Returns the node in a string of xml. 301 * Returns the node in a string of xml.
302 * 302 *
303 * @param node The starting node to output. 303 * @node: The starting node to output.
304 * @param len Address for the size of the string. 304 * @len: Address for the size of the string.
305 * 305 *
306 * @return The node represented as a string. You must 306 * Returns: The node represented as a string. You must
307 * g_free this string when finished using it. 307 * g_free this string when finished using it.
308 */ 308 */
309 char *purple_xmlnode_to_str(const PurpleXmlNode *node, int *len); 309 char *purple_xmlnode_to_str(const PurpleXmlNode *node, int *len);
310 310
311 /** 311 /**
312 * Returns the node in a string of human readable xml. 312 * Returns the node in a string of human readable xml.
313 * 313 *
314 * @param node The starting node to output. 314 * @node: The starting node to output.
315 * @param len Address for the size of the string. 315 * @len: Address for the size of the string.
316 * 316 *
317 * @return The node as human readable string including 317 * Returns: The node as human readable string including
318 * tab and new line characters. You must 318 * tab and new line characters. You must
319 * g_free this string when finished using it. 319 * g_free this string when finished using it.
320 */ 320 */
321 char *purple_xmlnode_to_formatted_str(const PurpleXmlNode *node, int *len); 321 char *purple_xmlnode_to_formatted_str(const PurpleXmlNode *node, int *len);
322 322
323 /** 323 /**
324 * Creates a node from a string of XML. Calling this on the 324 * Creates a node from a string of XML. Calling this on the
325 * root node of an XML document will parse the entire document 325 * root node of an XML document will parse the entire document
326 * into a tree of nodes, and return the PurpleXmlNode of the root. 326 * into a tree of nodes, and return the PurpleXmlNode of the root.
327 * 327 *
328 * @param str The string of xml. 328 * @str: The string of xml.
329 * @param size The size of the string, or -1 if @a str is 329 * @size: The size of the string, or -1 if @a str is
330 * NUL-terminated. 330 * NUL-terminated.
331 * 331 *
332 * @return The new node. 332 * Returns: The new node.
333 */ 333 */
334 PurpleXmlNode *purple_xmlnode_from_str(const char *str, gssize size); 334 PurpleXmlNode *purple_xmlnode_from_str(const char *str, gssize size);
335 335
336 /** 336 /**
337 * Creates a new node from the source node. 337 * Creates a new node from the source node.
338 * 338 *
339 * @param src The node to copy. 339 * @src: The node to copy.
340 * 340 *
341 * @return A new copy of the src node. 341 * Returns: A new copy of the src node.
342 */ 342 */
343 PurpleXmlNode *purple_xmlnode_copy(const PurpleXmlNode *src); 343 PurpleXmlNode *purple_xmlnode_copy(const PurpleXmlNode *src);
344 344
345 /** 345 /**
346 * Frees a node and all of its children. 346 * Frees a node and all of its children.
347 * 347 *
348 * @param node The node to free. 348 * @node: The node to free.
349 */ 349 */
350 void purple_xmlnode_free(PurpleXmlNode *node); 350 void purple_xmlnode_free(PurpleXmlNode *node);
351 351
352 /** 352 /**
353 * Creates a node from a XML File. Calling this on the 353 * Creates a node from a XML File. Calling this on the
354 * root node of an XML document will parse the entire document 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. 355 * into a tree of nodes, and return the PurpleXmlNode of the root.
356 * 356 *
357 * @param dir The directory where the file is located 357 * @dir: The directory where the file is located
358 * @param filename The filename 358 * @filename: The filename
359 * @param description A description of the file being parsed. Displayed to 359 * @description: A description of the file being parsed. Displayed to
360 * the user if the file cannot be read. 360 * the user if the file cannot be read.
361 * @param process The subsystem that is calling purple_xmlnode_from_file. Used as 361 * @process: The subsystem that is calling purple_xmlnode_from_file. Used as
362 * the category for debugging. 362 * the category for debugging.
363 * 363 *
364 * @return The new node or NULL if an error occurred. 364 * Returns: The new node or NULL if an error occurred.
365 */ 365 */
366 PurpleXmlNode *purple_xmlnode_from_file(const char *dir, const char *filename, 366 PurpleXmlNode *purple_xmlnode_from_file(const char *dir, const char *filename,
367 const char *description, const char *process); 367 const char *description, const char *process);
368 368
369 G_END_DECLS 369 G_END_DECLS

Mercurial Repository: pidgin3

mercurial