Mercurial > pidgin3 / file comparison

comparison: libpurple/protocols/facebook/json.h

libpurple/protocols/facebook/json.h

branch
facebook
changeset 37347
34d43f8c10d1
parent 37334
860ee76f5f58
child 37359
79374d83fae5
equal deleted inserted replaced
37346:ce9c78335820 37347:34d43f8c10d1
20 */ 20 */
21 21
22 #ifndef _FACEBOOK_JSON_H_ 22 #ifndef _FACEBOOK_JSON_H_
23 #define _FACEBOOK_JSON_H_ 23 #define _FACEBOOK_JSON_H_
24 24
25 /**
26 * SECTION:json
27 * @section_id: facebook-json
28 * @short_description: <filename>json.h</filename>
29 * @title: JSON Utilities
30 *
31 * The JSON utilities.
32 */
33
25 #include <glib.h> 34 #include <glib.h>
26 #include <json-glib/json-glib.h> 35 #include <json-glib/json-glib.h>
27 36
37 /**
38 * FB_JSON_ERROR:
39 *
40 * The #GQuark of the domain of JSON errors.
41 */
28 #define FB_JSON_ERROR fb_json_error_quark() 42 #define FB_JSON_ERROR fb_json_error_quark()
29 43
30 typedef enum _FbJsonError FbJsonError;
31 typedef enum _FbJsonType FbJsonType;
32 typedef struct _FbJsonValue FbJsonValue; 44 typedef struct _FbJsonValue FbJsonValue;
33 typedef struct _FbJsonValues FbJsonValues; 45 typedef struct _FbJsonValues FbJsonValues;
34 46
35 enum _FbJsonError 47 /**
48 * FbJsonError:
49 * @FB_JSON_ERROR_SUCCESS: There is no error.
50 * @FB_JSON_ERROR_AMBIGUOUS: The node has ambiguous matches.
51 * @FB_JSON_ERROR_GENERAL: General failure.
52 * @FB_JSON_ERROR_NOMATCH: The node does not match anything.
53 * @FB_JSON_ERROR_NULL: The node is of type NULL.
54 * @FB_JSON_ERROR_TYPE: The node has an unexpected type.
55 *
56 * The error codes for the #FB_JSON_ERROR domain.
57 */
58 typedef enum
36 { 59 {
37 FB_JSON_ERROR_SUCCESS = 0, 60 FB_JSON_ERROR_SUCCESS = 0,
38 FB_JSON_ERROR_AMBIGUOUS, 61 FB_JSON_ERROR_AMBIGUOUS,
39 FB_JSON_ERROR_GENERAL, 62 FB_JSON_ERROR_GENERAL,
40 FB_JSON_ERROR_NOMATCH, 63 FB_JSON_ERROR_NOMATCH,
41 FB_JSON_ERROR_NULL, 64 FB_JSON_ERROR_NULL,
42 FB_JSON_ERROR_TYPE 65 FB_JSON_ERROR_TYPE
43 }; 66 } FbJsonError;
44 67
45 enum _FbJsonType 68 /**
69 * FbJsonType:
70 * @FB_JSON_TYPE_NULL: An unknown value.
71 * @FB_JSON_TYPE_BOOL: A boolean (#TRUE or #FALSE).
72 * @FB_JSON_TYPE_DBL: A floating point number.
73 * @FB_JSON_TYPE_INT: A signed integer.
74 * @FB_JSON_TYPE_STR: A string.
75 *
76 * The JSON data types.
77 */
78 typedef enum
46 { 79 {
47 FB_JSON_TYPE_NULL = 0, 80 FB_JSON_TYPE_NULL = 0,
48 FB_JSON_TYPE_BOOL = G_TYPE_BOOLEAN, 81 FB_JSON_TYPE_BOOL = G_TYPE_BOOLEAN,
49 FB_JSON_TYPE_DBL = G_TYPE_DOUBLE, 82 FB_JSON_TYPE_DBL = G_TYPE_DOUBLE,
50 FB_JSON_TYPE_INT = G_TYPE_INT64, 83 FB_JSON_TYPE_INT = G_TYPE_INT64,
51 FB_JSON_TYPE_STR = G_TYPE_STRING 84 FB_JSON_TYPE_STR = G_TYPE_STRING
52 }; 85 } FbJsonType;
53 86
87 /**
88 * FbJsonValue:
89 * @expr: The #JsonPath expression.
90 * @type: The #FbJsonType.
91 * @required: TRUE if the node is required, otherwise FALSE.
92 * @value: The #GValue.
93 *
94 * Represents a JSON node value.
95 */
54 struct _FbJsonValue 96 struct _FbJsonValue
55 { 97 {
56 const gchar *expr; 98 const gchar *expr;
57 FbJsonType type; 99 FbJsonType type;
58 gboolean required; 100 gboolean required;
59 GValue value; 101 GValue value;
60 }; 102 };
61 103
104 /**
105 * FbJsonValues:
106 * @root: The root #JsonNode.
107 * @queue: The queue of #FbJsonValue's.
108 * @next: The next #FbJsonValue.
109 * @isarray: #TRUE if an array is present, otherwise #FALSE.
110 * @array: The #JsonArray or #NULL.
111 * @index: The advancing array index.
112 * @error: The #GError.
113 *
114 * Represents a JSON value handler.
115 */
62 struct _FbJsonValues 116 struct _FbJsonValues
63 { 117 {
64 JsonNode *root; 118 JsonNode *root;
65 GQueue *queue; 119 GQueue *queue;
66 GList *next; 120 GList *next;
70 guint index; 124 guint index;
71 125
72 GError *error; 126 GError *error;
73 }; 127 };
74 128
129 /**
130 * fb_json_error_quark:
131 *
132 * Gets the #GQuark of the domain of JSON errors.
133 *
134 * Returns: The #GQuark of the domain.
135 */
75 GQuark 136 GQuark
76 fb_json_error_quark(void); 137 fb_json_error_quark(void);
77 138
139 /**
140 * fb_json_bldr_new:
141 * @type: The starting #JsonNodeType.
142 *
143 * Creates a new #JsonBuilder. The starting #JsonNodeType is likely to
144 * be #JSON_NODE_OBJECT. The returned #JsonBuilder should be freed with
145 * #g_object_unref() when no longer needed. Optionally, instead of
146 * freeing, the returned #JsonBuilder can be closed with
147 * #fb_json_bldr_close().
148 *
149 * Returns: The new #JsonBuilder.
150 */
78 JsonBuilder * 151 JsonBuilder *
79 fb_json_bldr_new(JsonNodeType type); 152 fb_json_bldr_new(JsonNodeType type);
80 153
154 /**
155 * fb_json_bldr_close:
156 * @bldr: The #JsonBuilder.
157 * @type: The ending #JsonNodeType.
158 * @size: The return local for the size of the returned string.
159 *
160 * Closes the #JsonBuilder by returning a string representing the
161 * #JsonBuilder. The ending #JsonNodeType is likely to be
162 * #JSON_NODE_OBJECT. This calls #g_object_unref(). The returned
163 * string should be freed with #g_free() when no longer needed.
164 *
165 * Returns: The string representation of the #JsonBuilder.
166 */
81 gchar * 167 gchar *
82 fb_json_bldr_close(JsonBuilder *bldr, JsonNodeType type, gsize *size); 168 fb_json_bldr_close(JsonBuilder *bldr, JsonNodeType type, gsize *size);
83 169
170 /**
171 * fb_json_bldr_arr_begin:
172 * @bldr: The #JsonBuilder.
173 * @name: The member name, or #NULL.
174 *
175 * Begins an array member in the #JsonBuilder.
176 */
84 void 177 void
85 fb_json_bldr_arr_begin(JsonBuilder *bldr, const gchar *name); 178 fb_json_bldr_arr_begin(JsonBuilder *bldr, const gchar *name);
86 179
180 /**
181 * fb_json_bldr_arr_end:
182 * @bldr: The #JsonBuilder.
183 *
184 * Ends an array member in the #JsonBuilder.
185 */
87 void 186 void
88 fb_json_bldr_arr_end(JsonBuilder *bldr); 187 fb_json_bldr_arr_end(JsonBuilder *bldr);
89 188
189 /**
190 * fb_json_bldr_obj_begin:
191 * @bldr: The #JsonBuilder.
192 * @name: The member name, or #NULL.
193 *
194 * Begins an object member in the #JsonBuilder.
195 */
90 void 196 void
91 fb_json_bldr_obj_begin(JsonBuilder *bldr, const gchar *name); 197 fb_json_bldr_obj_begin(JsonBuilder *bldr, const gchar *name);
92 198
199 /**
200 * fb_json_bldr_obj_end:
201 * @bldr: The #JsonBuilder.
202 *
203 * Ends an array member in the #JsonBuilder.
204 */
93 void 205 void
94 fb_json_bldr_obj_end(JsonBuilder *bldr); 206 fb_json_bldr_obj_end(JsonBuilder *bldr);
95 207
208 /**
209 * fb_json_bldr_add_bool:
210 * @bldr: The #JsonBuilder.
211 * @name: The member name, or #NULL.
212 * @value: The value.
213 *
214 * Adds a boolean memeber to the #JsonBuilder.
215 */
96 void 216 void
97 fb_json_bldr_add_bool(JsonBuilder *bldr, const gchar *name, gboolean value); 217 fb_json_bldr_add_bool(JsonBuilder *bldr, const gchar *name, gboolean value);
98 218
219 /**
220 * fb_json_bldr_add_dbl:
221 * @bldr: The #JsonBuilder.
222 * @name: The member name, or #NULL.
223 * @value: The value.
224 *
225 * Adds a floating point memeber to the #JsonBuilder.
226 */
99 void 227 void
100 fb_json_bldr_add_dbl(JsonBuilder *bldr, const gchar *name, gdouble value); 228 fb_json_bldr_add_dbl(JsonBuilder *bldr, const gchar *name, gdouble value);
101 229
230 /**
231 * fb_json_bldr_add_int:
232 * @bldr: The #JsonBuilder.
233 * @name: The member name, or #NULL.
234 * @value: The value.
235 *
236 * Adds a integer memeber to the #JsonBuilder.
237 */
102 void 238 void
103 fb_json_bldr_add_int(JsonBuilder *bldr, const gchar *name, gint64 value); 239 fb_json_bldr_add_int(JsonBuilder *bldr, const gchar *name, gint64 value);
104 240
241 /**
242 * fb_json_bldr_add_str:
243 * @bldr: The #JsonBuilder.
244 * @name: The member name, or #NULL.
245 * @value: The value.
246 *
247 * Adds a string memeber to the #JsonBuilder.
248 */
105 void 249 void
106 fb_json_bldr_add_str(JsonBuilder *bldr, const gchar *name, const gchar *value); 250 fb_json_bldr_add_str(JsonBuilder *bldr, const gchar *name, const gchar *value);
107 251
252 /**
253 * fb_json_bldr_add_strf:
254 * @bldr: The #JsonBuilder.
255 * @name: The member name, or #NULL.
256 * @format: The format string literal.
257 * @...: The arguments for @format.
258 *
259 * Adds a formatted string memeber to the #JsonBuilder.
260 */
108 void 261 void
109 fb_json_bldr_add_strf(JsonBuilder *bldr, const gchar *name, 262 fb_json_bldr_add_strf(JsonBuilder *bldr, const gchar *name,
110 const gchar *format, ...) 263 const gchar *format, ...)
111 G_GNUC_PRINTF(3, 4); 264 G_GNUC_PRINTF(3, 4);
112 265
266 /**
267 * fb_json_node_new:
268 * @data: The string JSON.
269 * @size: The size of @json, or -1 if null-terminated.
270 * @error: The return location for the #GError, or #NULL.
271 *
272 * Creates a new #JsonNode. The returned #JsonBuilder should be freed
273 * wuth #json_node_free() when no longer needed.
274 *
275 * Returns: The new #JsonNode.
276 */
113 JsonNode * 277 JsonNode *
114 fb_json_node_new(const gchar *data, gssize size, GError **error); 278 fb_json_node_new(const gchar *data, gssize size, GError **error);
115 279
280 /**
281 * fb_json_node_get:
282 * @root: The root #JsonNode.
283 * @expr: The #JsonPath expression.
284 * @error: The return location for the #GError, or #NULL.
285 *
286 * Gets a new #JsonNode value from a parent #JsonNode with a #JsonPath
287 * expression. The returned #JsonNode should be freed with
288 * #json_node_free() when no longer needed.
289 *
290 * Returns: The new #JsonNode.
291 */
116 JsonNode * 292 JsonNode *
117 fb_json_node_get(JsonNode *root, const gchar *expr, GError **error); 293 fb_json_node_get(JsonNode *root, const gchar *expr, GError **error);
118 294
295 /**
296 * fb_json_node_get_nth:
297 * @root: The root #JsonNode.
298 * @n: The index number.
299 *
300 * Gets a #JsonNode value from a parent #JsonNode by index. The
301 * returned #JsonNode should not be freed.
302 *
303 * Return: The #JsonNode.
304 */
119 JsonNode * 305 JsonNode *
120 fb_json_node_get_nth(JsonNode *root, guint n); 306 fb_json_node_get_nth(JsonNode *root, guint n);
121 307
308 /**
309 * fb_json_node_get_arr:
310 * @root: The root #JsonNode.
311 * @expr: The #JsonPath expression.
312 * @error: The return location for the #GError, or #NULL.
313 *
314 * Gets a new #JsonArray value from a parent #JsonNode with a #JsonPath
315 * expression. The returned #JsonArray should be freed with
316 * #json_array_unref() when no longer needed.
317 *
318 * Returns: The new #JsonArray.
319 */
122 JsonArray * 320 JsonArray *
123 fb_json_node_get_arr(JsonNode *root, const gchar *expr, GError **error); 321 fb_json_node_get_arr(JsonNode *root, const gchar *expr, GError **error);
124 322
323 /**
324 * fb_json_node_get_bool:
325 * @root: The root #JsonNode.
326 * @expr: The #JsonPath expression.
327 * @error: The return location for the #GError, or #NULL.
328 *
329 * Gets a boolean value from a parent #JsonNode with a #JsonPath
330 * expression.
331 *
332 * Returns: The boolean value.
333 */
125 gboolean 334 gboolean
126 fb_json_node_get_bool(JsonNode *root, const gchar *expr, GError **error); 335 fb_json_node_get_bool(JsonNode *root, const gchar *expr, GError **error);
127 336
337 /**
338 * fb_json_node_get_dbl:
339 * @root: The root #JsonNode.
340 * @expr: The #JsonPath expression.
341 * @error: The return location for the #GError, or #NULL.
342 *
343 * Gets a floating point value from a parent #JsonNode with a #JsonPath
344 * expression.
345 *
346 * Returns: The floating point value.
347 */
128 gdouble 348 gdouble
129 fb_json_node_get_dbl(JsonNode *root, const gchar *expr, GError **error); 349 fb_json_node_get_dbl(JsonNode *root, const gchar *expr, GError **error);
130 350
351 /**
352 * fb_json_node_get_int:
353 * @root: The root #JsonNode.
354 * @expr: The #JsonPath expression.
355 * @error: The return location for the #GError, or #NULL.
356 *
357 * Gets an integer value from a parent #JsonNode with a #JsonPath
358 * expression.
359 *
360 * Returns: The integer value.
361 */
131 gint64 362 gint64
132 fb_json_node_get_int(JsonNode *root, const gchar *expr, GError **error); 363 fb_json_node_get_int(JsonNode *root, const gchar *expr, GError **error);
133 364
365 /**
366 * fb_json_node_get_str:
367 * @root: The root #JsonNode.
368 * @expr: The #JsonPath expression.
369 * @error: The return location for the #GError, or #NULL.
370 *
371 * Gets an string value from a parent #JsonNode with a #JsonPath
372 * expression. The returned string should be freed with #g_free()
373 * when no longer needed.
374 *
375 * Returns: The string value.
376 */
134 gchar * 377 gchar *
135 fb_json_node_get_str(JsonNode *root, const gchar *expr, GError **error); 378 fb_json_node_get_str(JsonNode *root, const gchar *expr, GError **error);
136 379
380 /**
381 * fb_json_values_new:
382 * @root: The root #JsonNode.
383 *
384 * Creates a new #FbJsonValues. The returned #FbJsonValues should be
385 * freed with #fb_json_values_free() when no longer needed.
386 *
387 * Returns: The new #FbJsonValues.
388 */
137 FbJsonValues * 389 FbJsonValues *
138 fb_json_values_new(JsonNode *root); 390 fb_json_values_new(JsonNode *root);
139 391
392 /**
393 * fb_json_values_free:
394 * @values: The #FbJsonValues.
395 *
396 * Frees all memory used by the #FbJsonValues.
397 */
140 void 398 void
141 fb_json_values_free(FbJsonValues *values); 399 fb_json_values_free(FbJsonValues *values);
142 400
401 /**
402 * fb_json_values_add:
403 * @values: The #FbJsonValues.
404 * @type: The #FbJsonType.
405 * @required: TRUE if the node is required, otherwise FALSE.
406 * @expr: The #JsonPath expression.
407 *
408 * Adds a new #FbJsonValue to the #FbJsonValues.
409 */
143 void 410 void
144 fb_json_values_add(FbJsonValues *values, FbJsonType type, gboolean required, 411 fb_json_values_add(FbJsonValues *values, FbJsonType type, gboolean required,
145 const gchar *expr); 412 const gchar *expr);
146 413
414 /**
415 * fb_json_values_get_root:
416 * @values: The #FbJsonValues.
417 *
418 * Gets the current working root #JsonNode. This is either the current
419 * array #JsonNode, or the root #JsonNode. The returned #JsonNode
420 * should not be freed.
421 */
147 JsonNode * 422 JsonNode *
148 fb_json_values_get_root(FbJsonValues *values); 423 fb_json_values_get_root(FbJsonValues *values);
149 424
425 /**
426 * fb_json_values_set_array:
427 * @values: The #FbJsonValues.
428 * @required: TRUE if the node is required, otherwise FALSE.
429 * @expr: The #JsonPath expression.
430 *
431 * Sets the #JsonPath for an array to base all #FbJsonValue's off.
432 */
150 void 433 void
151 fb_json_values_set_array(FbJsonValues *values, gboolean required, 434 fb_json_values_set_array(FbJsonValues *values, gboolean required,
152 const gchar *expr); 435 const gchar *expr);
153 436
437 /**
438 * fb_json_values_update:
439 * @values: The #FbJsonValues.
440 * @error: The return location for the #GError, or #NULL.
441 *
442 * Updates the current working root. This should be called after all of
443 * the #FbJsonValue's have been added with #fb_json_values_add(). If an
444 * array was set with #fb_json_values_set_array(), then this should be
445 * called in a while loop, until #FALSE is returned.
446 *
447 * Returns: #TRUE if the values were updated, otherwise #FALSE.
448 */
154 gboolean 449 gboolean
155 fb_json_values_update(FbJsonValues *values, GError **error); 450 fb_json_values_update(FbJsonValues *values, GError **error);
156 451
452 /**
453 * fb_json_values_next:
454 * @values: The #FbJsonValues.
455 *
456 * Gets the next #GValue from the #FbJsonValues. Before calling this
457 * function, #fb_json_values_update() must be called.
458 *
459 * Returns: The #GValue.
460 */
157 const GValue * 461 const GValue *
158 fb_json_values_next(FbJsonValues *values); 462 fb_json_values_next(FbJsonValues *values);
159 463
464 /**
465 * fb_json_values_next_bool:
466 * @values: The #FbJsonValues.
467 * @defval: The default value.
468 *
469 * Gets the next boolean value from the #FbJsonValues. Before calling
470 * this function, #fb_json_values_update() must be called.
471 *
472 * Returns: The boolean value.
473 */
160 gboolean 474 gboolean
161 fb_json_values_next_bool(FbJsonValues *values, gboolean defval); 475 fb_json_values_next_bool(FbJsonValues *values, gboolean defval);
162 476
477 /**
478 * fb_json_values_next_dbl:
479 * @values: The #FbJsonValues.
480 * @defval: The default value.
481 *
482 * Gets the next floating point value from the #FbJsonValues. Before
483 * calling this function, #fb_json_values_update() must be called.
484 *
485 * Returns: The floating point value.
486 */
163 gdouble 487 gdouble
164 fb_json_values_next_dbl(FbJsonValues *values, gdouble defval); 488 fb_json_values_next_dbl(FbJsonValues *values, gdouble defval);
165 489
490 /**
491 * fb_json_values_next_int:
492 * @values: The #FbJsonValues.
493 * @defval: The default value.
494 *
495 * Gets the next integer value from the #FbJsonValues. Before calling
496 * this function, #fb_json_values_update() must be called.
497 *
498 * Returns: The integer value.
499 */
166 gint64 500 gint64
167 fb_json_values_next_int(FbJsonValues *values, gint64 defval); 501 fb_json_values_next_int(FbJsonValues *values, gint64 defval);
168 502
503 /**
504 * fb_json_values_next_str:
505 * @values: The #FbJsonValues.
506 * @defval: The default value.
507 *
508 * Gets the next string value from the #FbJsonValues. Before calling
509 * this function, #fb_json_values_update() must be called.
510 *
511 * Returns: The string value.
512 */
169 const gchar * 513 const gchar *
170 fb_json_values_next_str(FbJsonValues *values, const gchar *defval); 514 fb_json_values_next_str(FbJsonValues *values, const gchar *defval);
171 515
516 /**
517 * fb_json_values_next_str_dup:
518 * @values: The #FbJsonValues.
519 * @defval: The default value.
520 *
521 * Gets the next duplicate string value from the #FbJsonValues. Before
522 * calling this function, #fb_json_values_update() must be called.
523 *
524 * Returns: The duplicate string value.
525 */
172 gchar * 526 gchar *
173 fb_json_values_next_str_dup(FbJsonValues *values, const gchar *defval); 527 fb_json_values_next_str_dup(FbJsonValues *values, const gchar *defval);
174 528
175 #endif /* _FACEBOOK_JSON_H_ */ 529 #endif /* _FACEBOOK_JSON_H_ */

Mercurial Repository: pidgin3

mercurial