summaryrefslogtreecommitdiffstats
path: root/include/plist/plist.h
diff options
context:
space:
mode:
Diffstat (limited to 'include/plist/plist.h')
-rw-r--r--include/plist/plist.h1388
1 files changed, 695 insertions, 693 deletions
diff --git a/include/plist/plist.h b/include/plist/plist.h
index 699a0d6..d3f0836 100644
--- a/include/plist/plist.h
+++ b/include/plist/plist.h
@@ -8,22 +8,23 @@
8 * modify it under the terms of the GNU Lesser General Public 8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either 9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version. 10 * version 2.1 of the License, or (at your option) any later version.
11 * 11 *
12 * This library is distributed in the hope that it will be useful, 12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details. 15 * Lesser General Public License for more details.
16 * 16 *
17 * You should have received a copy of the GNU Lesser General Public 17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, write to the Free Software 18 * License along with this library; if not, write to the Free Software
19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
20 */ 20 */
21 21
22#ifndef LIBPLIST_H 22#ifndef LIBPLIST_H
23#define LIBPLIST_H 23#define LIBPLIST_H
24 24
25#ifdef __cplusplus 25#ifdef __cplusplus
26extern "C" { 26extern "C"
27{
27#endif 28#endif
28 29
29#ifdef _MSC_VER 30#ifdef _MSC_VER
@@ -37,705 +38,706 @@ extern "C" {
37 typedef unsigned __int32 uint32_t; 38 typedef unsigned __int32 uint32_t;
38 typedef unsigned __int64 uint64_t; 39 typedef unsigned __int64 uint64_t;
39 40
40 #ifdef plist_EXPORTS 41#ifdef plist_EXPORTS
41 #define PLIST_API __declspec( dllexport ) 42#define PLIST_API __declspec( dllexport )
42 #else 43#else
43 #define PLIST_API __declspec( dllimport ) 44#define PLIST_API __declspec( dllimport )
44 #endif 45#endif
45#else 46#else
46 #include <stdint.h> 47#include <stdint.h>
47 #define PLIST_API 48#define PLIST_API
48#endif 49#endif
49 50
50#include <sys/types.h> 51#include <sys/types.h>
51#include <stdarg.h> 52#include <stdarg.h>
52 53
53/** 54 /**
54 * \mainpage libplist : A library to handle Apple Property Lists 55 * \mainpage libplist : A library to handle Apple Property Lists
55 * \defgroup PublicAPI Public libplist API 56 * \defgroup PublicAPI Public libplist API
56 */ 57 */
57/*@{*/ 58 /*@{*/
58 59
59 60
60/** 61 /**
61 * The basic plist abstract data type. 62 * The basic plist abstract data type.
62 */ 63 */
63 typedef void *plist_t; 64 typedef void *plist_t;
64 65
65/** 66 /**
66 * The plist dictionary iterator. 67 * The plist dictionary iterator.
67 */ 68 */
68 typedef void *plist_dict_iter; 69 typedef void *plist_dict_iter;
69 70
70/** 71 /**
71 * The enumeration of plist node types. 72 * The enumeration of plist node types.
72 */ 73 */
73 typedef enum { 74 typedef enum
74 PLIST_BOOLEAN, /**< Boolean, scalar type */ 75 {
75 PLIST_UINT, /**< Unsigned integer, scalar type */ 76 PLIST_BOOLEAN, /**< Boolean, scalar type */
76 PLIST_REAL, /**< Real, scalar type */ 77 PLIST_UINT, /**< Unsigned integer, scalar type */
77 PLIST_STRING, /**< ASCII string, scalar type */ 78 PLIST_REAL, /**< Real, scalar type */
78 PLIST_ARRAY, /**< Ordered array, structured type */ 79 PLIST_STRING, /**< ASCII string, scalar type */
79 PLIST_DICT, /**< Unordered dictionary (key/value pair), structured type */ 80 PLIST_ARRAY, /**< Ordered array, structured type */
80 PLIST_DATE, /**< Date, scalar type */ 81 PLIST_DICT, /**< Unordered dictionary (key/value pair), structured type */
81 PLIST_DATA, /**< Binary data, scalar type */ 82 PLIST_DATE, /**< Date, scalar type */
82 PLIST_KEY, /**< Key in dictionaries (ASCII String), scalar type */ 83 PLIST_DATA, /**< Binary data, scalar type */
83 PLIST_NONE /**< No type */ 84 PLIST_KEY, /**< Key in dictionaries (ASCII String), scalar type */
84 } plist_type; 85 PLIST_NONE /**< No type */
85 86 } plist_type;
86 87
87/******************************************** 88
88 * * 89 /********************************************
89 * Creation & Destruction * 90 * *
90 * * 91 * Creation & Destruction *
91 ********************************************/ 92 * *
92 93 ********************************************/
93/** 94
94 * Create a new root plist_t type #PLIST_DICT 95 /**
95 * 96 * Create a new root plist_t type #PLIST_DICT
96 * @return the created plist 97 *
97 * @sa #plist_type 98 * @return the created plist
98 */ 99 * @sa #plist_type
99 PLIST_API plist_t plist_new_dict(void); 100 */
100 101 PLIST_API plist_t plist_new_dict(void);
101/** 102
102 * Create a new root plist_t type #PLIST_ARRAY 103 /**
103 * 104 * Create a new root plist_t type #PLIST_ARRAY
104 * @return the created plist 105 *
105 * @sa #plist_type 106 * @return the created plist
106 */ 107 * @sa #plist_type
107 PLIST_API plist_t plist_new_array(void); 108 */
108 109 PLIST_API plist_t plist_new_array(void);
109/** 110
110 * Create a new plist_t type #PLIST_STRING 111 /**
111 * 112 * Create a new plist_t type #PLIST_STRING
112 * @param val the sting value, encoded in UTF8. 113 *
113 * @return the created item 114 * @param val the sting value, encoded in UTF8.
114 * @sa #plist_type 115 * @return the created item
115 */ 116 * @sa #plist_type
116 PLIST_API plist_t plist_new_string(const char *val); 117 */
117 118 PLIST_API plist_t plist_new_string(const char *val);
118/** 119
119 * Create a new plist_t type #PLIST_BOOLEAN 120 /**
120 * 121 * Create a new plist_t type #PLIST_BOOLEAN
121 * @param val the boolean value, 0 is false, other values are true. 122 *
122 * @return the created item 123 * @param val the boolean value, 0 is false, other values are true.
123 * @sa #plist_type 124 * @return the created item
124 */ 125 * @sa #plist_type
125 PLIST_API plist_t plist_new_bool(uint8_t val); 126 */
126 127 PLIST_API plist_t plist_new_bool(uint8_t val);
127/** 128
128 * Create a new plist_t type #PLIST_UINT 129 /**
129 * 130 * Create a new plist_t type #PLIST_UINT
130 * @param val the unsigned integer value 131 *
131 * @return the created item 132 * @param val the unsigned integer value
132 * @sa #plist_type 133 * @return the created item
133 */ 134 * @sa #plist_type
134 PLIST_API plist_t plist_new_uint(uint64_t val); 135 */
135 136 PLIST_API plist_t plist_new_uint(uint64_t val);
136/** 137
137 * Create a new plist_t type #PLIST_REAL 138 /**
138 * 139 * Create a new plist_t type #PLIST_REAL
139 * @param val the real value 140 *
140 * @return the created item 141 * @param val the real value
141 * @sa #plist_type 142 * @return the created item
142 */ 143 * @sa #plist_type
143 PLIST_API plist_t plist_new_real(double val); 144 */
144 145 PLIST_API plist_t plist_new_real(double val);
145/** 146
146 * Create a new plist_t type #PLIST_DATA 147 /**
147 * 148 * Create a new plist_t type #PLIST_DATA
148 * @param val the binary buffer 149 *
149 * @param length the length of the buffer 150 * @param val the binary buffer
150 * @return the created item 151 * @param length the length of the buffer
151 * @sa #plist_type 152 * @return the created item
152 */ 153 * @sa #plist_type
153 PLIST_API plist_t plist_new_data(const char *val, uint64_t length); 154 */
154 155 PLIST_API plist_t plist_new_data(const char *val, uint64_t length);
155/** 156
156 * Create a new plist_t type #PLIST_DATE 157 /**
157 * 158 * Create a new plist_t type #PLIST_DATE
158 * @param sec the number of seconds since 01/01/2001 159 *
159 * @param usec the number of microseconds 160 * @param sec the number of seconds since 01/01/2001
160 * @return the created item 161 * @param usec the number of microseconds
161 * @sa #plist_type 162 * @return the created item
162 */ 163 * @sa #plist_type
163 PLIST_API plist_t plist_new_date(int32_t sec, int32_t usec); 164 */
164 165 PLIST_API plist_t plist_new_date(int32_t sec, int32_t usec);
165/** 166
166 * Destruct a plist_t node and all its children recursively 167 /**
167 * 168 * Destruct a plist_t node and all its children recursively
168 * @param plist the plist to free 169 *
169 */ 170 * @param plist the plist to free
170 PLIST_API void plist_free(plist_t plist); 171 */
171 172 PLIST_API void plist_free(plist_t plist);
172/** 173
173 * Return a copy of passed node and it's children 174 /**
174 * 175 * Return a copy of passed node and it's children
175 * @param plist the plist to copy 176 *
176 * @return copied plist 177 * @param plist the plist to copy
177 */ 178 * @return copied plist
178 PLIST_API plist_t plist_copy(plist_t node); 179 */
179 180 PLIST_API plist_t plist_copy(plist_t node);
180 181
181/******************************************** 182
182 * * 183 /********************************************
183 * Array functions * 184 * *
184 * * 185 * Array functions *
185 ********************************************/ 186 * *
186 187 ********************************************/
187/** 188
188 * Get size of a #PLIST_ARRAY node. 189 /**
189 * 190 * Get size of a #PLIST_ARRAY node.
190 * @param node the node of type #PLIST_ARRAY 191 *
191 * @return size of the #PLIST_ARRAY node 192 * @param node the node of type #PLIST_ARRAY
192 */ 193 * @return size of the #PLIST_ARRAY node
193 PLIST_API uint32_t plist_array_get_size(plist_t node); 194 */
194 195 PLIST_API uint32_t plist_array_get_size(plist_t node);
195/** 196
196 * Get the nth item in a #PLIST_ARRAY node. 197 /**
197 * 198 * Get the nth item in a #PLIST_ARRAY node.
198 * @param node the node of type #PLIST_ARRAY 199 *
199 * @param n the index of the item to get. Range is [0, array_size[ 200 * @param node the node of type #PLIST_ARRAY
200 * @return the nth item or NULL if node is not of type #PLIST_ARRAY 201 * @param n the index of the item to get. Range is [0, array_size[
201 */ 202 * @return the nth item or NULL if node is not of type #PLIST_ARRAY
202 PLIST_API plist_t plist_array_get_item(plist_t node, uint32_t n); 203 */
203 204 PLIST_API plist_t plist_array_get_item(plist_t node, uint32_t n);
204/** 205
205 * Get the index of an item. item must be a member of a #PLIST_ARRAY node. 206 /**
206 * 207 * Get the index of an item. item must be a member of a #PLIST_ARRAY node.
207 * @param node the node 208 *
208 * @return the node index 209 * @param node the node
209 */ 210 * @return the node index
210 PLIST_API uint32_t plist_array_get_item_index(plist_t node); 211 */
211 212 PLIST_API uint32_t plist_array_get_item_index(plist_t node);
212/** 213
213 * Set the nth item in a #PLIST_ARRAY node. 214 /**
214 * The previous item at index n will be freed using #plist_free 215 * Set the nth item in a #PLIST_ARRAY node.
215 * 216 * The previous item at index n will be freed using #plist_free
216 * @param node the node of type #PLIST_ARRAY 217 *
217 * @param item the new item at index n 218 * @param node the node of type #PLIST_ARRAY
218 * @param n the index of the item to get. Range is [0, array_size[. Assert if n is not in range. 219 * @param item the new item at index n
219 */ 220 * @param n the index of the item to get. Range is [0, array_size[. Assert if n is not in range.
220 PLIST_API void plist_array_set_item(plist_t node, plist_t item, uint32_t n); 221 */
221 222 PLIST_API void plist_array_set_item(plist_t node, plist_t item, uint32_t n);
222/** 223
223 * Append a new item at the end of a #PLIST_ARRAY node. 224 /**
224 * 225 * Append a new item at the end of a #PLIST_ARRAY node.
225 * @param node the node of type #PLIST_ARRAY 226 *
226 * @param item the new item 227 * @param node the node of type #PLIST_ARRAY
227 */ 228 * @param item the new item
228 PLIST_API void plist_array_append_item(plist_t node, plist_t item); 229 */
229 230 PLIST_API void plist_array_append_item(plist_t node, plist_t item);
230/** 231
231 * Insert a new item at position n in a #PLIST_ARRAY node. 232 /**
232 * 233 * Insert a new item at position n in a #PLIST_ARRAY node.
233 * @param node the node of type #PLIST_ARRAY 234 *
234 * @param item the new item to insert 235 * @param node the node of type #PLIST_ARRAY
235 * @param n The position at which the node will be stored. Range is [0, array_size[. Assert if n is not in range. 236 * @param item the new item to insert
236 */ 237 * @param n The position at which the node will be stored. Range is [0, array_size[. Assert if n is not in range.
237 PLIST_API void plist_array_insert_item(plist_t node, plist_t item, uint32_t n); 238 */
238 239 PLIST_API void plist_array_insert_item(plist_t node, plist_t item, uint32_t n);
239/** 240
240 * Remove an existing position in a #PLIST_ARRAY node. 241 /**
241 * Removed position will be freed using #plist_free 242 * Remove an existing position in a #PLIST_ARRAY node.
242 * 243 * Removed position will be freed using #plist_free
243 * @param node the node of type #PLIST_ARRAY 244 *
244 * @param n The position to remove. Range is [0, array_size[. Assert if n is not in range. 245 * @param node the node of type #PLIST_ARRAY
245 */ 246 * @param n The position to remove. Range is [0, array_size[. Assert if n is not in range.
246 PLIST_API void plist_array_remove_item(plist_t node, uint32_t n); 247 */
247 248 PLIST_API void plist_array_remove_item(plist_t node, uint32_t n);
248/******************************************** 249
249 * * 250 /********************************************
250 * Dictionary functions * 251 * *
251 * * 252 * Dictionary functions *
252 ********************************************/ 253 * *
253 254 ********************************************/
254/** 255
255 * Get size of a #PLIST_DICT node. 256 /**
256 * 257 * Get size of a #PLIST_DICT node.
257 * @param node the node of type #PLIST_DICT 258 *
258 * @return size of the #PLIST_DICT node 259 * @param node the node of type #PLIST_DICT
259 */ 260 * @return size of the #PLIST_DICT node
260 PLIST_API uint32_t plist_dict_get_size(plist_t node); 261 */
261 262 PLIST_API uint32_t plist_dict_get_size(plist_t node);
262/** 263
263 * Create iterator of a #PLIST_DICT node. 264 /**
264 * The allocated iterator shoult be freed with tandard free function 265 * Create iterator of a #PLIST_DICT node.
265 * 266 * The allocated iterator shoult be freed with tandard free function
266 * @param node the node of type #PLIST_DICT 267 *
267 * @param iter iterator of the #PLIST_DICT node 268 * @param node the node of type #PLIST_DICT
268 */ 269 * @param iter iterator of the #PLIST_DICT node
269 PLIST_API void plist_dict_new_iter(plist_t node, plist_dict_iter *iter); 270 */
270 271 PLIST_API void plist_dict_new_iter(plist_t node, plist_dict_iter *iter);
271/** 272
272 * Increment iterator of a #PLIST_DICT node. 273 /**
273 * 274 * Increment iterator of a #PLIST_DICT node.
274 * @param node the node of type #PLIST_DICT 275 *
275 * @param iter iterator of the dictionary 276 * @param node the node of type #PLIST_DICT
276 * @param key a location to store the key, or NULL. 277 * @param iter iterator of the dictionary
277 * @param val a location to store the value, or NULL. 278 * @param key a location to store the key, or NULL.
278 */ 279 * @param val a location to store the value, or NULL.
279 PLIST_API void plist_dict_next_item(plist_t node, plist_dict_iter iter, char **key, plist_t *val); 280 */
280 281 PLIST_API void plist_dict_next_item(plist_t node, plist_dict_iter iter, char **key, plist_t *val);
281/** 282
282 * Get key associated to an item. Item must be member of a dictionary 283 /**
283 * 284 * Get key associated to an item. Item must be member of a dictionary
284 * @param node the node 285 *
285 * @param key a location to store the key. 286 * @param node the node
286 */ 287 * @param key a location to store the key.
287 PLIST_API void plist_dict_get_item_key(plist_t node, char **key); 288 */
288 289 PLIST_API void plist_dict_get_item_key(plist_t node, char **key);
289/** 290
290 * Get the nth item in a #PLIST_DICT node. 291 /**
291 * 292 * Get the nth item in a #PLIST_DICT node.
292 * @param node the node of type #PLIST_DICT 293 *
293 * @param key the identifier of the item to get. 294 * @param node the node of type #PLIST_DICT
294 * @return the item or NULL if node is not of type #PLIST_DICT 295 * @param key the identifier of the item to get.
295 */ 296 * @return the item or NULL if node is not of type #PLIST_DICT
296 PLIST_API plist_t plist_dict_get_item(plist_t node, const char* key); 297 */
297 298 PLIST_API plist_t plist_dict_get_item(plist_t node, const char* key);
298/** 299
299 * Set item identified by key in a #PLIST_DICT node. 300 /**
300 * The previous item at index n will be freed using #plist_free 301 * Set item identified by key in a #PLIST_DICT node.
301 * 302 * The previous item at index n will be freed using #plist_free
302 * @param node the node of type #PLIST_DICT 303 *
303 * @param item the new item associated to key 304 * @param node the node of type #PLIST_DICT
304 * @param key the identifier of the item to get. Assert if identifier is not present. 305 * @param item the new item associated to key
305 */ 306 * @param key the identifier of the item to get. Assert if identifier is not present.
306 PLIST_API void plist_dict_set_item(plist_t node, const char* key, plist_t item); 307 */
307 308 PLIST_API void plist_dict_set_item(plist_t node, const char* key, plist_t item);
308/** 309
309 * Insert a new item at position n in a #PLIST_DICT node. 310 /**
310 * 311 * Insert a new item at position n in a #PLIST_DICT node.
311 * @param node the node of type #PLIST_DICT 312 *
312 * @param item the new item to insert 313 * @param node the node of type #PLIST_DICT
313 * @param key The identifier of the item to insert. Assert if identifier already present. 314 * @param item the new item to insert
314 */ 315 * @param key The identifier of the item to insert. Assert if identifier already present.
315 PLIST_API void plist_dict_insert_item(plist_t node, const char* key, plist_t item); 316 */
316 317 PLIST_API void plist_dict_insert_item(plist_t node, const char* key, plist_t item);
317/** 318
318 * Remove an existing position in a #PLIST_DICT node. 319 /**
319 * Removed position will be freed using #plist_free 320 * Remove an existing position in a #PLIST_DICT node.
320 * 321 * Removed position will be freed using #plist_free
321 * @param node the node of type #PLIST_DICT 322 *
322 * @param key The identifier of the item to remove. Assert if identifier is not present. 323 * @param node the node of type #PLIST_DICT
323 */ 324 * @param key The identifier of the item to remove. Assert if identifier is not present.
324 PLIST_API void plist_dict_remove_item(plist_t node, const char* key); 325 */
325 326 PLIST_API void plist_dict_remove_item(plist_t node, const char* key);
326 327
327/******************************************** 328
328 * * 329 /********************************************
329 * Getters * 330 * *
330 * * 331 * Getters *
331 ********************************************/ 332 * *
332 333 ********************************************/
333/** 334
334 * Get the parent of a node 335 /**
335 * 336 * Get the parent of a node
336 * @param node the parent (NULL if node is root) 337 *
337 */ 338 * @param node the parent (NULL if node is root)
338 PLIST_API plist_t plist_get_parent(plist_t node); 339 */
339 340 PLIST_API plist_t plist_get_parent(plist_t node);
340/** 341
341 * Get the #plist_type of a node. 342 /**
342 * 343 * Get the #plist_type of a node.
343 * @param node the node 344 *
344 * @return the type of the node 345 * @param node the node
345 */ 346 * @return the type of the node
346 PLIST_API plist_type plist_get_node_type(plist_t node); 347 */
347 348 PLIST_API plist_type plist_get_node_type(plist_t node);
348/** 349
349 * Get the value of a #PLIST_KEY node. 350 /**
350 * This function does nothing if node is not of type #PLIST_KEY 351 * Get the value of a #PLIST_KEY node.
351 * 352 * This function does nothing if node is not of type #PLIST_KEY
352 * @param node the node 353 *
353 * @param val a pointer to a C-string. This function allocates the memory, 354 * @param node the node
354 * caller is responsible for freeing it. 355 * @param val a pointer to a C-string. This function allocates the memory,
355 */ 356 * caller is responsible for freeing it.
356 PLIST_API void plist_get_key_val(plist_t node, char **val); 357 */
357 358 PLIST_API void plist_get_key_val(plist_t node, char **val);
358/** 359
359 * Get the value of a #PLIST_STRING node. 360 /**
360 * This function does nothing if node is not of type #PLIST_STRING 361 * Get the value of a #PLIST_STRING node.
361 * 362 * This function does nothing if node is not of type #PLIST_STRING
362 * @param node the node 363 *
363 * @param val a pointer to a C-string. This function allocates the memory, 364 * @param node the node
364 * caller is responsible for freeing it. Data is UTF-8 encoded. 365 * @param val a pointer to a C-string. This function allocates the memory,
365 */ 366 * caller is responsible for freeing it. Data is UTF-8 encoded.
366 PLIST_API void plist_get_string_val(plist_t node, char **val); 367 */
367 368 PLIST_API void plist_get_string_val(plist_t node, char **val);
368/** 369
369 * Get the value of a #PLIST_BOOLEAN node. 370 /**
370 * This function does nothing if node is not of type #PLIST_BOOLEAN 371 * Get the value of a #PLIST_BOOLEAN node.
371 * 372 * This function does nothing if node is not of type #PLIST_BOOLEAN
372 * @param node the node 373 *
373 * @param val a pointer to a uint8_t variable. 374 * @param node the node
374 */ 375 * @param val a pointer to a uint8_t variable.
375 PLIST_API void plist_get_bool_val(plist_t node, uint8_t * val); 376 */
376 377 PLIST_API void plist_get_bool_val(plist_t node, uint8_t * val);
377/** 378
378 * Get the value of a #PLIST_UINT node. 379 /**
379 * This function does nothing if node is not of type #PLIST_UINT 380 * Get the value of a #PLIST_UINT node.
380 * 381 * This function does nothing if node is not of type #PLIST_UINT
381 * @param node the node 382 *
382 * @param val a pointer to a uint64_t variable. 383 * @param node the node
383 */ 384 * @param val a pointer to a uint64_t variable.
384 PLIST_API void plist_get_uint_val(plist_t node, uint64_t * val); 385 */
385 386 PLIST_API void plist_get_uint_val(plist_t node, uint64_t * val);
386/** 387
387 * Get the value of a #PLIST_REAL node. 388 /**
388 * This function does nothing if node is not of type #PLIST_REAL 389 * Get the value of a #PLIST_REAL node.
389 * 390 * This function does nothing if node is not of type #PLIST_REAL
390 * @param node the node 391 *
391 * @param val a pointer to a double variable. 392 * @param node the node
392 */ 393 * @param val a pointer to a double variable.
393 PLIST_API void plist_get_real_val(plist_t node, double *val); 394 */
394 395 PLIST_API void plist_get_real_val(plist_t node, double *val);
395/** 396
396 * Get the value of a #PLIST_DATA node. 397 /**
397 * This function does nothing if node is not of type #PLIST_DATA 398 * Get the value of a #PLIST_DATA node.
398 * 399 * This function does nothing if node is not of type #PLIST_DATA
399 * @param node the node 400 *
400 * @param val a pointer to an unallocated char buffer. This function allocates the memory, 401 * @param node the node
401 * caller is responsible for freeing it. 402 * @param val a pointer to an unallocated char buffer. This function allocates the memory,
402 */ 403 * caller is responsible for freeing it.
403 PLIST_API void plist_get_data_val(plist_t node, char **val, uint64_t * length); 404 */
404 405 PLIST_API void plist_get_data_val(plist_t node, char **val, uint64_t * length);
405/** 406
406 * Get the value of a #PLIST_DATE node. 407 /**
407 * This function does nothing if node is not of type #PLIST_DATE 408 * Get the value of a #PLIST_DATE node.
408 * 409 * This function does nothing if node is not of type #PLIST_DATE
409 * @param node the node 410 *
410 * @param sec a pointer to an int32_t variable. Represents the number of seconds since 01/01/2001. 411 * @param node the node
411 * @param usec a pointer to an int32_t variable. Represents the number of microseconds 412 * @param sec a pointer to an int32_t variable. Represents the number of seconds since 01/01/2001.
412 */ 413 * @param usec a pointer to an int32_t variable. Represents the number of microseconds
413 PLIST_API void plist_get_date_val(plist_t node, int32_t * sec, int32_t * usec); 414 */
414 415 PLIST_API void plist_get_date_val(plist_t node, int32_t * sec, int32_t * usec);
415 416
416/******************************************** 417
417 * * 418 /********************************************
418 * Setters * 419 * *
419 * * 420 * Setters *
420 ********************************************/ 421 * *
421 422 ********************************************/
422/** 423
423 * Forces type of node. Changing type of structured nodes is only allowed if node is empty. 424 /**
424 * Reset value of node; 425 * Forces type of node. Changing type of structured nodes is only allowed if node is empty.
425 * @param node the node 426 * Reset value of node;
426 * @param type the key value 427 * @param node the node
427 */ 428 * @param type the key value
428 PLIST_API void plist_set_type(plist_t node, plist_type type); 429 */
429 430 PLIST_API void plist_set_type(plist_t node, plist_type type);
430/** 431
431 * Set the value of a node. 432 /**
432 * Forces type of node to #PLIST_KEY 433 * Set the value of a node.
433 * 434 * Forces type of node to #PLIST_KEY
434 * @param node the node 435 *
435 * @param val the key value 436 * @param node the node
436 */ 437 * @param val the key value
437 PLIST_API void plist_set_key_val(plist_t node, const char *val); 438 */
438 439 PLIST_API void plist_set_key_val(plist_t node, const char *val);
439/** 440
440 * Set the value of a node. 441 /**
441 * Forces type of node to #PLIST_STRING 442 * Set the value of a node.
442 * 443 * Forces type of node to #PLIST_STRING
443 * @param node the node 444 *
444 * @param val the string value 445 * @param node the node
445 */ 446 * @param val the string value
446 PLIST_API void plist_set_string_val(plist_t node, const char *val); 447 */
447 448 PLIST_API void plist_set_string_val(plist_t node, const char *val);
448/** 449
449 * Set the value of a node. 450 /**
450 * Forces type of node to #PLIST_BOOLEAN 451 * Set the value of a node.
451 * 452 * Forces type of node to #PLIST_BOOLEAN
452 * @param node the node 453 *
453 * @param val the boolean value 454 * @param node the node
454 */ 455 * @param val the boolean value
455 PLIST_API void plist_set_bool_val(plist_t node, uint8_t val); 456 */
456 457 PLIST_API void plist_set_bool_val(plist_t node, uint8_t val);
457/** 458
458 * Set the value of a node. 459 /**
459 * Forces type of node to #PLIST_UINT 460 * Set the value of a node.
460 * 461 * Forces type of node to #PLIST_UINT
461 * @param node the node 462 *
462 * @param val the unsigned integer value 463 * @param node the node
463 */ 464 * @param val the unsigned integer value
464 PLIST_API void plist_set_uint_val(plist_t node, uint64_t val); 465 */
465 466 PLIST_API void plist_set_uint_val(plist_t node, uint64_t val);
466/** 467
467 * Set the value of a node. 468 /**
468 * Forces type of node to #PLIST_REAL 469 * Set the value of a node.
469 * 470 * Forces type of node to #PLIST_REAL
470 * @param node the node 471 *
471 * @param val the real value 472 * @param node the node
472 */ 473 * @param val the real value
473 PLIST_API void plist_set_real_val(plist_t node, double val); 474 */
474 475 PLIST_API void plist_set_real_val(plist_t node, double val);
475/** 476
476 * Set the value of a node. 477 /**
477 * Forces type of node to #PLIST_DATA 478 * Set the value of a node.
478 * 479 * Forces type of node to #PLIST_DATA
479 * @param node the node 480 *
480 * @param val the binary buffer 481 * @param node the node
481 * @param length the length of the buffer 482 * @param val the binary buffer
482 */ 483 * @param length the length of the buffer
483 PLIST_API void plist_set_data_val(plist_t node, const char *val, uint64_t length); 484 */
484 485 PLIST_API void plist_set_data_val(plist_t node, const char *val, uint64_t length);
485/** 486
486 * Set the value of a node. 487 /**
487 * Forces type of node to #PLIST_DATE 488 * Set the value of a node.
488 * 489 * Forces type of node to #PLIST_DATE
489 * @param node the node 490 *
490 * @param sec the number of seconds since 01/01/2001 491 * @param node the node
491 * @param usec the number of microseconds 492 * @param sec the number of seconds since 01/01/2001
492 */ 493 * @param usec the number of microseconds
493 PLIST_API void plist_set_date_val(plist_t node, int32_t sec, int32_t usec); 494 */
494 495 PLIST_API void plist_set_date_val(plist_t node, int32_t sec, int32_t usec);
495 496
496/******************************************** 497
497 * * 498 /********************************************
498 * Import & Export * 499 * *
499 * * 500 * Import & Export *
500 ********************************************/ 501 * *
501 502 ********************************************/
502/** 503
503 * Export the #plist_t structure to XML format. 504 /**
504 * 505 * Export the #plist_t structure to XML format.
505 * @param plist the root node to export 506 *
506 * @param plist_xml a pointer to a C-string. This function allocates the memory, 507 * @param plist the root node to export
507 * caller is responsible for freeing it. Data is UTF-8 encoded. 508 * @param plist_xml a pointer to a C-string. This function allocates the memory,
508 * @param length a pointer to an uint32_t variable. Represents the length of the allocated buffer. 509 * caller is responsible for freeing it. Data is UTF-8 encoded.
509 */ 510 * @param length a pointer to an uint32_t variable. Represents the length of the allocated buffer.
510 PLIST_API void plist_to_xml(plist_t plist, char **plist_xml, uint32_t * length); 511 */
511 512 PLIST_API void plist_to_xml(plist_t plist, char **plist_xml, uint32_t * length);
512/** 513
513 * Export the #plist_t structure to binary format. 514 /**
514 * 515 * Export the #plist_t structure to binary format.
515 * @param plist the root node to export 516 *
516 * @param plist_bin a pointer to a char* buffer. This function allocates the memory, 517 * @param plist the root node to export
517 * caller is responsible for freeing it. 518 * @param plist_bin a pointer to a char* buffer. This function allocates the memory,
518 * @param length a pointer to an uint32_t variable. Represents the length of the allocated buffer. 519 * caller is responsible for freeing it.
519 */ 520 * @param length a pointer to an uint32_t variable. Represents the length of the allocated buffer.
520 PLIST_API void plist_to_bin(plist_t plist, char **plist_bin, uint32_t * length); 521 */
521 522 PLIST_API void plist_to_bin(plist_t plist, char **plist_bin, uint32_t * length);
522/** 523
523 * Import the #plist_t structure from XML format. 524 /**
524 * 525 * Import the #plist_t structure from XML format.
525 * @param plist_xml a pointer to the xml buffer. 526 *
526 * @param length length of the buffer to read. 527 * @param plist_xml a pointer to the xml buffer.
527 * @param plist a pointer to the imported plist. 528 * @param length length of the buffer to read.
528 */ 529 * @param plist a pointer to the imported plist.
529 PLIST_API void plist_from_xml(const char *plist_xml, uint32_t length, plist_t * plist); 530 */
530 531 PLIST_API void plist_from_xml(const char *plist_xml, uint32_t length, plist_t * plist);
531/** 532
532 * Import the #plist_t structure from binary format. 533 /**
533 * 534 * Import the #plist_t structure from binary format.
534 * @param plist_bin a pointer to the xml buffer. 535 *
535 * @param length length of the buffer to read. 536 * @param plist_bin a pointer to the xml buffer.
536 * @param plist a pointer to the imported plist. 537 * @param length length of the buffer to read.
537 */ 538 * @param plist a pointer to the imported plist.
538 PLIST_API void plist_from_bin(const char *plist_bin, uint32_t length, plist_t * plist); 539 */
539 540 PLIST_API void plist_from_bin(const char *plist_bin, uint32_t length, plist_t * plist);
540 541
541/******************************************** 542
542 * * 543 /********************************************
543 * Utils * 544 * *
544 * * 545 * Utils *
545 ********************************************/ 546 * *
546 547 ********************************************/
547/** 548
548 * Get a node from its path. Each path element depends on the associated father node type. 549 /**
549 * For Dictionaries, var args are casted to const char*, for arrays, var args are caster to uint32_t 550 * Get a node from its path. Each path element depends on the associated father node type.
550 * Search is breath first order. 551 * For Dictionaries, var args are casted to const char*, for arrays, var args are caster to uint32_t
551 * 552 * Search is breath first order.
552 * @param plist the node to access result from. 553 *
553 * @param length length of the path to access 554 * @param plist the node to access result from.
554 * @return the value to access. 555 * @param length length of the path to access
555 */ 556 * @return the value to access.
556 PLIST_API plist_t plist_access_path(plist_t plist, uint32_t length, ...); 557 */
557 558 PLIST_API plist_t plist_access_path(plist_t plist, uint32_t length, ...);
558/** 559
559 * Variadic version of #plist_access_path. 560 /**
560 * 561 * Variadic version of #plist_access_path.
561 * @param plist the node to access result from. 562 *
562 * @param length length of the path to access 563 * @param plist the node to access result from.
563 * @param v list of array's index and dic'st key 564 * @param length length of the path to access
564 * @return the value to access. 565 * @param v list of array's index and dic'st key
565 */ 566 * @return the value to access.
566 PLIST_API plist_t plist_access_pathv(plist_t plist, uint32_t length, va_list v); 567 */
567 568 PLIST_API plist_t plist_access_pathv(plist_t plist, uint32_t length, va_list v);
568/** 569
569 * Compare two node values 570 /**
570 * 571 * Compare two node values
571 * @param node_l left node to compare 572 *
572 * @param node_r rigth node to compare 573 * @param node_l left node to compare
573 * @return TRUE is type and value match, FALSE otherwise. 574 * @param node_r rigth node to compare
574 */ 575 * @return TRUE is type and value match, FALSE otherwise.
575 PLIST_API char plist_compare_node_value(plist_t node_l, plist_t node_r); 576 */
577 PLIST_API char plist_compare_node_value(plist_t node_l, plist_t node_r);
576 578
577 579
578//DEPRECATED API BELOW 580//DEPRECATED API BELOW
579 581
580/*@}*/ 582 /*@}*/
581/** 583 /**
582 * \defgroup DeprecatedAPI Deprecated libplist API 584 * \defgroup DeprecatedAPI Deprecated libplist API
583 */ 585 */
584/*@{*/ 586 /*@{*/
585 587
586/******************************************** 588 /********************************************
587 * * 589 * *
588 * Tree navigation * 590 * Tree navigation *
589 * * 591 * *
590 ********************************************/ 592 ********************************************/
591 593
592/** 594 /**
593 * Get the first child of a node 595 * Get the first child of a node
594 * 596 *
595 * @param node the first child 597 * @param node the first child
596 */ 598 */
597 PLIST_API plist_t plist_get_first_child(plist_t node); 599 PLIST_API plist_t plist_get_first_child(plist_t node);
598 600
599/** 601 /**
600 * Get the next sibling of a node 602 * Get the next sibling of a node
601 * 603 *
602 * @param node the next sibling 604 * @param node the next sibling
603 */ 605 */
604 PLIST_API plist_t plist_get_next_sibling(plist_t node); 606 PLIST_API plist_t plist_get_next_sibling(plist_t node);
605 607
606/** 608 /**
607 * Get the previous sibling of a node 609 * Get the previous sibling of a node
608 * 610 *
609 * @param node the previous sibling 611 * @param node the previous sibling
610 */ 612 */
611 PLIST_API plist_t plist_get_prev_sibling(plist_t node); 613 PLIST_API plist_t plist_get_prev_sibling(plist_t node);
612 614
613/** 615 /**
614 * Get the nth child of a #PLIST_ARRAY node. 616 * Get the nth child of a #PLIST_ARRAY node.
615 * 617 *
616 * @param node the node of type #PLIST_ARRAY 618 * @param node the node of type #PLIST_ARRAY
617 * @param n the index of the child to get. Range is [0, array_size[ 619 * @param n the index of the child to get. Range is [0, array_size[
618 * @return the nth children or NULL if node is not of type #PLIST_ARRAY 620 * @return the nth children or NULL if node is not of type #PLIST_ARRAY
619 */ 621 */
620 PLIST_API plist_t plist_get_array_nth_el(plist_t node, uint32_t n); 622 PLIST_API plist_t plist_get_array_nth_el(plist_t node, uint32_t n);
621 623
622/** 624 /**
623 * Get the child of a #PLIST_DICT node from the associated key value. 625 * Get the child of a #PLIST_DICT node from the associated key value.
624 * 626 *
625 * @param node the node of type #PLIST_DICT 627 * @param node the node of type #PLIST_DICT
626 * @param key the key associated to the requested value 628 * @param key the key associated to the requested value
627 * @return the key associated value or NULL if node is not of type #PLIST_DICT 629 * @return the key associated value or NULL if node is not of type #PLIST_DICT
628 */ 630 */
629 PLIST_API plist_t plist_get_dict_el_from_key(plist_t node, const char *key); 631 PLIST_API plist_t plist_get_dict_el_from_key(plist_t node, const char *key);
630 632
631 633
632/******************************************** 634 /********************************************
633 * * 635 * *
634 * Setters * 636 * Setters *
635 * * 637 * *
636 ********************************************/ 638 ********************************************/
637 639
638/** 640 /**
639 * Add a subnode to a node. The node must be of a structured type 641 * Add a subnode to a node. The node must be of a structured type
640 * (ie #PLIST_DICT or #PLIST_ARRAY). This function fails silently 642 * (ie #PLIST_DICT or #PLIST_ARRAY). This function fails silently
641 * if subnode already has a father. 643 * if subnode already has a father.
642 * 644 *
643 * @param node the node to add a children to 645 * @param node the node to add a children to
644 * @param subnode the children node 646 * @param subnode the children node
645 */ 647 */
646 PLIST_API void plist_add_sub_node(plist_t node, plist_t subnode); 648 PLIST_API void plist_add_sub_node(plist_t node, plist_t subnode);
647 649
648/** 650 /**
649 * Add a subnode of type #PLIST_KEY to a node. The node must be of a structured type 651 * Add a subnode of type #PLIST_KEY to a node. The node must be of a structured type
650 * (ie #PLIST_DICT or #PLIST_ARRAY). 652 * (ie #PLIST_DICT or #PLIST_ARRAY).
651 * 653 *
652 * @param node the node to add a children to 654 * @param node the node to add a children to
653 * @param val the key value encoded as an ASCII string (must be null terminated) 655 * @param val the key value encoded as an ASCII string (must be null terminated)
654 */ 656 */
655 PLIST_API void plist_add_sub_key_el(plist_t node, const char *val); 657 PLIST_API void plist_add_sub_key_el(plist_t node, const char *val);
656 658
657/** 659 /**
658 * Add a subnode of type #PLIST_STRING to a node. The node must be of a structured type 660 * Add a subnode of type #PLIST_STRING to a node. The node must be of a structured type
659 * (ie #PLIST_DICT or #PLIST_ARRAY). 661 * (ie #PLIST_DICT or #PLIST_ARRAY).
660 * 662 *
661 * @param node the node to add a children to 663 * @param node the node to add a children to
662 * @param val the string value encoded as an ASCII or UTF-8 string (must be null terminated) 664 * @param val the string value encoded as an ASCII or UTF-8 string (must be null terminated)
663 */ 665 */
664 PLIST_API void plist_add_sub_string_el(plist_t node, const char *val); 666 PLIST_API void plist_add_sub_string_el(plist_t node, const char *val);
665 667
666/** 668 /**
667 * Add a subnode of type #PLIST_BOOLEAN to a node. The node must be of a structured type 669 * Add a subnode of type #PLIST_BOOLEAN to a node. The node must be of a structured type
668 * (ie #PLIST_DICT or #PLIST_ARRAY). 670 * (ie #PLIST_DICT or #PLIST_ARRAY).
669 * 671 *
670 * @param node the node to add a children to 672 * @param node the node to add a children to
671 * @param val the boolean value (TRUE or FALSE) 673 * @param val the boolean value (TRUE or FALSE)
672 */ 674 */
673 PLIST_API void plist_add_sub_bool_el(plist_t node, uint8_t val); 675 PLIST_API void plist_add_sub_bool_el(plist_t node, uint8_t val);
674 676
675/** 677 /**
676 * Add a subnode of type #PLIST_UINT to a node. The node must be of a structured type 678 * Add a subnode of type #PLIST_UINT to a node. The node must be of a structured type
677 * (ie #PLIST_DICT or #PLIST_ARRAY). 679 * (ie #PLIST_DICT or #PLIST_ARRAY).
678 * 680 *
679 * @param node the node to add a children to 681 * @param node the node to add a children to
680 * @param val the unsigned integer value 682 * @param val the unsigned integer value
681 */ 683 */
682 PLIST_API void plist_add_sub_uint_el(plist_t node, uint64_t val); 684 PLIST_API void plist_add_sub_uint_el(plist_t node, uint64_t val);
683 685
684/** 686 /**
685 * Add a subnode of type #PLIST_REAL to a node. The node must be of a structured type 687 * Add a subnode of type #PLIST_REAL to a node. The node must be of a structured type
686 * (ie #PLIST_DICT or #PLIST_ARRAY). 688 * (ie #PLIST_DICT or #PLIST_ARRAY).
687 * 689 *
688 * @param node the node to add a children to 690 * @param node the node to add a children to
689 * @param val the real value 691 * @param val the real value
690 */ 692 */
691 PLIST_API void plist_add_sub_real_el(plist_t node, double val); 693 PLIST_API void plist_add_sub_real_el(plist_t node, double val);
692 694
693/** 695 /**
694 * Add a subnode of type #PLIST_DATA to a node. The node must be of a structured type 696 * Add a subnode of type #PLIST_DATA to a node. The node must be of a structured type
695 * (ie #PLIST_DICT or #PLIST_ARRAY). 697 * (ie #PLIST_DICT or #PLIST_ARRAY).
696 * 698 *
697 * @param node the node to add a children to 699 * @param node the node to add a children to
698 * @param val the binary buffer 700 * @param val the binary buffer
699 * @param length the length of the buffer 701 * @param length the length of the buffer
700 */ 702 */
701 PLIST_API void plist_add_sub_data_el(plist_t node, const char *val, uint64_t length); 703 PLIST_API void plist_add_sub_data_el(plist_t node, const char *val, uint64_t length);
702 704
703/** 705 /**
704 * Add a subnode of type #PLIST_DATE to a node. The node must be of a structured type 706 * Add a subnode of type #PLIST_DATE to a node. The node must be of a structured type
705 * (ie #PLIST_DICT or #PLIST_ARRAY). 707 * (ie #PLIST_DICT or #PLIST_ARRAY).
706 * 708 *
707 * @param node the node to add a children to 709 * @param node the node to add a children to
708 * @param sec the number of seconds since 01/01/2001 710 * @param sec the number of seconds since 01/01/2001
709 * @param usec the number of microseconds 711 * @param usec the number of microseconds
710 */ 712 */
711 PLIST_API void plist_add_sub_date_el(plist_t node, int32_t sec, int32_t usec); 713 PLIST_API void plist_add_sub_date_el(plist_t node, int32_t sec, int32_t usec);
712 714
713 715
714/******************************************** 716 /********************************************
715 * * 717 * *
716 * Utils * 718 * Utils *
717 * * 719 * *
718 ********************************************/ 720 ********************************************/
719 721
720/** 722 /**
721 * Find the first encountered #PLIST_KEY node mathing that key. 723 * Find the first encountered #PLIST_KEY node mathing that key.
722 * Search is breath first order. 724 * Search is breath first order.
723 * 725 *
724 * @param plist the root node of the plist structure. 726 * @param plist the root node of the plist structure.
725 * @param value the ASCII Key to match. 727 * @param value the ASCII Key to match.
726 */ 728 */
727 PLIST_API plist_t plist_find_node_by_key(plist_t plist, const char *value); 729 PLIST_API plist_t plist_find_node_by_key(plist_t plist, const char *value);
728 730
729/** 731 /**
730 * Find the first encountered #PLIST_STRING node mathing that string. 732 * Find the first encountered #PLIST_STRING node mathing that string.
731 * Search is breath first order. 733 * Search is breath first order.
732 * 734 *
733 * @param plist the root node of the plist structure. 735 * @param plist the root node of the plist structure.
734 * @param value the ASCII String to match. 736 * @param value the ASCII String to match.
735 */ 737 */
736 PLIST_API plist_t plist_find_node_by_string(plist_t plist, const char *value); 738 PLIST_API plist_t plist_find_node_by_string(plist_t plist, const char *value);
737 739
738/*@}*/ 740 /*@}*/
739 741
740 742
741#ifdef __cplusplus 743#ifdef __cplusplus
© 2009-2020 sukimashita.com - Generated by cgit - Icons from Tango - Uses Google Analytics