comparison src/xmlnode.h @ 10327:d88ee1d73a93

[gaim-migrate @ 11534] Doxumentation from Gary. Thanks mon ami! committer: Tailor Script <tailor@pidgin.im>
author Mark Doliner <mark@kingant.net>
date Wed, 08 Dec 2004 00:20:38 +0000
parents dafebadcf8d2
children 682201b69107
comparison
equal deleted inserted replaced
10326:72f671a4e153 10327:d88ee1d73a93
1 /** 1 /**
2 * @file xmlnode.h XML DOM functions 2 * @file xmlnode.h XML DOM functions
3 * @ingroup core
3 * 4 *
4 * gaim 5 * gaim
5 * 6 *
6 * Gaim is the legal property of its developers, whose names are too numerous 7 * Gaim is the legal property of its developers, whose names are too numerous
7 * to list here. Please refer to the COPYRIGHT file distributed with this 8 * to list here. Please refer to the COPYRIGHT file distributed with this
22 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
23 */ 24 */
24 #ifndef _GAIM_XMLNODE_H_ 25 #ifndef _GAIM_XMLNODE_H_
25 #define _GAIM_XMLNODE_H_ 26 #define _GAIM_XMLNODE_H_
26 27
28 /**
29 * The valid types for an xmlnode
30 */
27 typedef enum _XMLNodeType 31 typedef enum _XMLNodeType
28 { 32 {
29 XMLNODE_TYPE_TAG, 33 XMLNODE_TYPE_TAG, /**< Just a tag */
30 XMLNODE_TYPE_ATTRIB, 34 XMLNODE_TYPE_ATTRIB, /**< Has attributes */
31 XMLNODE_TYPE_DATA 35 XMLNODE_TYPE_DATA /**< Has data */
32 } XMLNodeType; 36 } XMLNodeType;
33 37
38 /**
39 * An xmlnode.
40 */
34 typedef struct _xmlnode 41 typedef struct _xmlnode
35 { 42 {
36 char *name; 43 char *name; /**< The name of the node. */
37 XMLNodeType type; 44 XMLNodeType type; /**< The type of the node. */
38 char *data; 45 char *data; /**< The data for the node. */
39 size_t data_sz; 46 size_t data_sz; /**< The size of the data. */
40 struct _xmlnode *parent; 47 struct _xmlnode *parent; /**< The parent node or @c NULL.*/
41 struct _xmlnode *child; 48 struct _xmlnode *child; /**< The child node or @c NULL.*/
42 struct _xmlnode *next; 49 struct _xmlnode *next; /**< The next node or @c NULL. */
43 } xmlnode; 50 } xmlnode;
44 51
52 /**
53 * Creates a new xmlnode.
54 *
55 * @param name The name of the node.
56 *
57 * @return The new node.
58 */
45 xmlnode *xmlnode_new(const char *name); 59 xmlnode *xmlnode_new(const char *name);
60
61 /**
62 * Creates a new xmlnode child.
63 *
64 * @param parent The parent node.
65 * @param name The name of the child node.
66 *
67 * @return The new child node.
68 */
46 xmlnode *xmlnode_new_child(xmlnode *parent, const char *name); 69 xmlnode *xmlnode_new_child(xmlnode *parent, const char *name);
70
71 /**
72 * Inserts a node into a node as a child.
73 *
74 * @param parent The parent node to insert child into.
75 * @param child The child node to insert into parent.
76 */
47 void xmlnode_insert_child(xmlnode *parent, xmlnode *child); 77 void xmlnode_insert_child(xmlnode *parent, xmlnode *child);
78
79 /**
80 * Gets a child node named name.
81 *
82 * @param parent The parent node.
83 * @param name The child's name.
84 *
85 * @return The child or NULL.
86 */
48 xmlnode *xmlnode_get_child(xmlnode *parent, const char *name); 87 xmlnode *xmlnode_get_child(xmlnode *parent, const char *name);
88
89 /**
90 * Gets a child node named name in a namespace.
91 *
92 * @param parent The parent node.
93 * @param name The child's name.
94 * @param xmlns The namespace.
95 *
96 * @return The child or NULL.
97 */
49 xmlnode *xmlnode_get_child_with_namespace(xmlnode *parent, const char *name, const char *xmlns); 98 xmlnode *xmlnode_get_child_with_namespace(xmlnode *parent, const char *name, const char *xmlns);
99
100 /**
101 * Gets the next node with the same name as node.
102 *
103 * @param node The node of a twin to find.
104 *
105 * @return The twin of node or NULL.
106 */
50 xmlnode *xmlnode_get_next_twin(xmlnode *node); 107 xmlnode *xmlnode_get_next_twin(xmlnode *node);
108
109 /**
110 * Inserts data into a node.
111 *
112 * @param parent The node to insert data into.
113 * @param data The data to insert.
114 * @param size The size of the data to insert.
115 */
51 void xmlnode_insert_data(xmlnode *parent, const char *data, size_t size); 116 void xmlnode_insert_data(xmlnode *parent, const char *data, size_t size);
117
118 /**
119 * Gets data from a node.
120 *
121 * @param node The node to get data from.
122 *
123 * @return The data from the node.
124 */
52 char *xmlnode_get_data(xmlnode *node); 125 char *xmlnode_get_data(xmlnode *node);
126
127 /**
128 * Sets an attribute for a node.
129 *
130 * @param node The node to set an attribute for.
131 * @param attr The name of the attribute.
132 * @param value The value of the attribute.
133 */
53 void xmlnode_set_attrib(xmlnode *node, const char *attr, const char *value); 134 void xmlnode_set_attrib(xmlnode *node, const char *attr, const char *value);
135
136 /**
137 * Gets an attribute from a node.
138 *
139 * @param node The node to get an attribute from.
140 * @param attr The attribute to get.
141 *
142 * @return The value of the attribute.
143 */
54 const char *xmlnode_get_attrib(xmlnode *node, const char *attr); 144 const char *xmlnode_get_attrib(xmlnode *node, const char *attr);
145
146 /**
147 * Removes an attribute from a node.
148 *
149 * @param node The node to remove an attribute from.
150 * @param attr The attribute to remove.
151 */
55 void xmlnode_remove_attrib(xmlnode *node, const char *attr); 152 void xmlnode_remove_attrib(xmlnode *node, const char *attr);
153
154 /**
155 * Returns the node in a string of xml.
156 *
157 * @param node The starting node to output.
158 * @param len Address for the size of the string.
159 *
160 * @return The node repersented as a string.
161 */
56 char *xmlnode_to_str(xmlnode *node, int *len); 162 char *xmlnode_to_str(xmlnode *node, int *len);
163
164 /**
165 * Returns the node in a string of human readable xml.
166 *
167 * @param node The starting node to output.
168 * @param len Address for the size of the string.
169 *
170 * @return The node as human readable string including
171 * tab and new line characters.
172 */
57 char *xmlnode_to_formatted_str(xmlnode *node, int *len); 173 char *xmlnode_to_formatted_str(xmlnode *node, int *len);
174
175 /**
176 * Creates a node from a string of xml.
177 *
178 * @param str The string of xml.
179 * @param size The size of the string.
180 *
181 * @return The new node.
182 */
58 xmlnode *xmlnode_from_str(const char *str, size_t size); 183 xmlnode *xmlnode_from_str(const char *str, size_t size);
184
185 /**
186 * Creates a new node from the source node.
187 *
188 * @param src The node to copy.
189 *
190 * @return A new copy of the src node.
191 */
59 xmlnode *xmlnode_copy(xmlnode *src); 192 xmlnode *xmlnode_copy(xmlnode *src);
60 193
194 /**
195 * Frees a node and all of it's children.
196 *
197 * @param node The node to free.
198 */
61 void xmlnode_free(xmlnode *node); 199 void xmlnode_free(xmlnode *node);
62 200
63 #endif /* _GAIM_XMLNODE_H_ */ 201 #endif /* _GAIM_XMLNODE_H_ */