comparison: libpurple/protocols/facebook/json.h
libpurple/protocols/facebook/json.h
- changeset 42187
- fc241db9162d
- parent 42186
- 637ba5491231
- child 42188
- 04c0398f1046
equal
deleted
inserted
replaced
| 42186:637ba5491231 | 42187:fc241db9162d |
|---|---|
| 1 /* purple | |
| 2 * | |
| 3 * Purple is the legal property of its developers, whose names are too numerous | |
| 4 * to list here. Please refer to the COPYRIGHT file distributed with this | |
| 5 * source distribution. | |
| 6 * | |
| 7 * This program is free software; you can redistribute it and/or modify | |
| 8 * it under the terms of the GNU General Public License as published by | |
| 9 * the Free Software Foundation; either version 2 of the License, or | |
| 10 * (at your option) any later version. | |
| 11 * | |
| 12 * This program is distributed in the hope that it will be useful, | |
| 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
| 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
| 15 * GNU General Public License for more details. | |
| 16 * | |
| 17 * You should have received a copy of the GNU General Public License | |
| 18 * along with this program; if not, write to the Free Software | |
| 19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA | |
| 20 */ | |
| 21 | |
| 22 #ifndef PURPLE_FACEBOOK_JSON_H | |
| 23 #define PURPLE_FACEBOOK_JSON_H | |
| 24 | |
| 25 #include <glib.h> | |
| 26 #include <json-glib/json-glib.h> | |
| 27 | |
| 28 #define FB_TYPE_JSON_VALUES fb_json_values_get_type() | |
| 29 | |
| 30 /** | |
| 31 * FB_JSON_ERROR: | |
| 32 * | |
| 33 * The #GQuark of the domain of JSON errors. | |
| 34 */ | |
| 35 #define FB_JSON_ERROR fb_json_error_quark() | |
| 36 | |
| 37 /** | |
| 38 * FbJsonError: | |
| 39 * @FB_JSON_ERROR_SUCCESS: There is no error. | |
| 40 * @FB_JSON_ERROR_AMBIGUOUS: The node has ambiguous matches. | |
| 41 * @FB_JSON_ERROR_GENERAL: General failure. | |
| 42 * @FB_JSON_ERROR_NOMATCH: The node does not match anything. | |
| 43 * @FB_JSON_ERROR_NULL: The node is of type NULL. | |
| 44 * @FB_JSON_ERROR_TYPE: The node has an unexpected type. | |
| 45 * | |
| 46 * The error codes for the #FB_JSON_ERROR domain. | |
| 47 */ | |
| 48 typedef enum | |
| 49 { | |
| 50 FB_JSON_ERROR_SUCCESS = 0, | |
| 51 FB_JSON_ERROR_AMBIGUOUS, | |
| 52 FB_JSON_ERROR_GENERAL, | |
| 53 FB_JSON_ERROR_NOMATCH, | |
| 54 FB_JSON_ERROR_NULL, | |
| 55 FB_JSON_ERROR_TYPE | |
| 56 } FbJsonError; | |
| 57 | |
| 58 /** | |
| 59 * FbJsonType: | |
| 60 * @FB_JSON_TYPE_NULL: An unknown value. | |
| 61 * @FB_JSON_TYPE_BOOL: A boolean (#TRUE or #FALSE). | |
| 62 * @FB_JSON_TYPE_DBL: A floating point number. | |
| 63 * @FB_JSON_TYPE_INT: A signed integer. | |
| 64 * @FB_JSON_TYPE_STR: A string. | |
| 65 * | |
| 66 * The JSON data types. | |
| 67 */ | |
| 68 typedef enum | |
| 69 { | |
| 70 FB_JSON_TYPE_NULL = 0, | |
| 71 FB_JSON_TYPE_BOOL = G_TYPE_BOOLEAN, | |
| 72 FB_JSON_TYPE_DBL = G_TYPE_DOUBLE, | |
| 73 FB_JSON_TYPE_INT = G_TYPE_INT64, | |
| 74 FB_JSON_TYPE_STR = G_TYPE_STRING | |
| 75 } FbJsonType; | |
| 76 | |
| 77 G_DECLARE_FINAL_TYPE(FbJsonValues, fb_json_values, FB, JSON_VALUES, | |
| 78 GObject) | |
| 79 | |
| 80 /** | |
| 81 * fb_json_error_quark: | |
| 82 * | |
| 83 * Gets the #GQuark of the domain of JSON errors. | |
| 84 * | |
| 85 * Returns: The #GQuark of the domain. | |
| 86 */ | |
| 87 GQuark | |
| 88 fb_json_error_quark(void); | |
| 89 | |
| 90 /** | |
| 91 * fb_json_bldr_new: | |
| 92 * @type: The starting #JsonNodeType. | |
| 93 * | |
| 94 * Creates a new #JsonBuilder. The starting #JsonNodeType is likely to | |
| 95 * be #JSON_NODE_OBJECT. The returned #JsonBuilder should be freed with | |
| 96 * #g_object_unref() when no longer needed. Optionally, instead of | |
| 97 * freeing, the returned #JsonBuilder can be closed with | |
| 98 * #fb_json_bldr_close(). | |
| 99 * | |
| 100 * Returns: (transfer full): The new #JsonBuilder. | |
| 101 */ | |
| 102 JsonBuilder * | |
| 103 fb_json_bldr_new(JsonNodeType type); | |
| 104 | |
| 105 /** | |
| 106 * fb_json_bldr_close: | |
| 107 * @bldr: The #JsonBuilder. | |
| 108 * @type: The ending #JsonNodeType. | |
| 109 * @size: The return local for the size of the returned string. | |
| 110 * | |
| 111 * Closes the #JsonBuilder by returning a string representing the | |
| 112 * #JsonBuilder. The ending #JsonNodeType is likely to be | |
| 113 * #JSON_NODE_OBJECT. This calls #g_object_unref(). The returned | |
| 114 * string should be freed with #g_free() when no longer needed. | |
| 115 * | |
| 116 * Returns: The string representation of the #JsonBuilder. | |
| 117 */ | |
| 118 gchar * | |
| 119 fb_json_bldr_close(JsonBuilder *bldr, JsonNodeType type, gsize *size); | |
| 120 | |
| 121 /** | |
| 122 * fb_json_bldr_arr_begin: | |
| 123 * @bldr: The #JsonBuilder. | |
| 124 * @name: The member name or #NULL. | |
| 125 * | |
| 126 * Begins an array member in the #JsonBuilder. | |
| 127 */ | |
| 128 void | |
| 129 fb_json_bldr_arr_begin(JsonBuilder *bldr, const gchar *name); | |
| 130 | |
| 131 /** | |
| 132 * fb_json_bldr_arr_end: | |
| 133 * @bldr: The #JsonBuilder. | |
| 134 * | |
| 135 * Ends an array member in the #JsonBuilder. | |
| 136 */ | |
| 137 void | |
| 138 fb_json_bldr_arr_end(JsonBuilder *bldr); | |
| 139 | |
| 140 /** | |
| 141 * fb_json_bldr_obj_begin: | |
| 142 * @bldr: The #JsonBuilder. | |
| 143 * @name: The member name or #NULL. | |
| 144 * | |
| 145 * Begins an object member in the #JsonBuilder. | |
| 146 */ | |
| 147 void | |
| 148 fb_json_bldr_obj_begin(JsonBuilder *bldr, const gchar *name); | |
| 149 | |
| 150 /** | |
| 151 * fb_json_bldr_obj_end: | |
| 152 * @bldr: The #JsonBuilder. | |
| 153 * | |
| 154 * Ends an array member in the #JsonBuilder. | |
| 155 */ | |
| 156 void | |
| 157 fb_json_bldr_obj_end(JsonBuilder *bldr); | |
| 158 | |
| 159 /** | |
| 160 * fb_json_bldr_add_bool: | |
| 161 * @bldr: The #JsonBuilder. | |
| 162 * @name: The member name or #NULL. | |
| 163 * @value: The value. | |
| 164 * | |
| 165 * Adds a boolean member to the #JsonBuilder. | |
| 166 */ | |
| 167 void | |
| 168 fb_json_bldr_add_bool(JsonBuilder *bldr, const gchar *name, gboolean value); | |
| 169 | |
| 170 /** | |
| 171 * fb_json_bldr_add_dbl: | |
| 172 * @bldr: The #JsonBuilder. | |
| 173 * @name: The member name or #NULL. | |
| 174 * @value: The value. | |
| 175 * | |
| 176 * Adds a floating point member to the #JsonBuilder. | |
| 177 */ | |
| 178 void | |
| 179 fb_json_bldr_add_dbl(JsonBuilder *bldr, const gchar *name, gdouble value); | |
| 180 | |
| 181 /** | |
| 182 * fb_json_bldr_add_int: | |
| 183 * @bldr: The #JsonBuilder. | |
| 184 * @name: The member name or #NULL. | |
| 185 * @value: The value. | |
| 186 * | |
| 187 * Adds an integer member to the #JsonBuilder. | |
| 188 */ | |
| 189 void | |
| 190 fb_json_bldr_add_int(JsonBuilder *bldr, const gchar *name, gint64 value); | |
| 191 | |
| 192 /** | |
| 193 * fb_json_bldr_add_str: | |
| 194 * @bldr: The #JsonBuilder. | |
| 195 * @name: The member name or #NULL. | |
| 196 * @value: The value. | |
| 197 * | |
| 198 * Adds a string member to the #JsonBuilder. | |
| 199 */ | |
| 200 void | |
| 201 fb_json_bldr_add_str(JsonBuilder *bldr, const gchar *name, const gchar *value); | |
| 202 | |
| 203 /** | |
| 204 * fb_json_bldr_add_strf: | |
| 205 * @bldr: The #JsonBuilder. | |
| 206 * @name: The member name or #NULL. | |
| 207 * @format: The format string literal. | |
| 208 * @...: The arguments for @format. | |
| 209 * | |
| 210 * Adds a formatted string member to the #JsonBuilder. | |
| 211 */ | |
| 212 void | |
| 213 fb_json_bldr_add_strf(JsonBuilder *bldr, const gchar *name, | |
| 214 const gchar *format, ...) | |
| 215 G_GNUC_PRINTF(3, 4); | |
| 216 | |
| 217 /** | |
| 218 * fb_json_node_new: | |
| 219 * @data: The string JSON. | |
| 220 * @size: The size of @json or -1 if null-terminated. | |
| 221 * @error: The return location for the #GError or #NULL. | |
| 222 * | |
| 223 * Creates a new #JsonNode. The returned #JsonBuilder should be freed | |
| 224 * wuth #json_node_free() when no longer needed. | |
| 225 * | |
| 226 * Returns: The new #JsonNode. | |
| 227 */ | |
| 228 JsonNode * | |
| 229 fb_json_node_new(const gchar *data, gssize size, GError **error); | |
| 230 | |
| 231 /** | |
| 232 * fb_json_node_get: | |
| 233 * @root: The root #JsonNode. | |
| 234 * @expr: The #JsonPath expression. | |
| 235 * @error: The return location for the #GError or #NULL. | |
| 236 * | |
| 237 * Gets a new #JsonNode value from a parent #JsonNode with a #JsonPath | |
| 238 * expression. The returned #JsonNode should be freed with | |
| 239 * #json_node_free() when no longer needed. | |
| 240 * | |
| 241 * Returns: The new #JsonNode. | |
| 242 */ | |
| 243 JsonNode * | |
| 244 fb_json_node_get(JsonNode *root, const gchar *expr, GError **error); | |
| 245 | |
| 246 /** | |
| 247 * fb_json_node_get_nth: | |
| 248 * @root: The root #JsonNode. | |
| 249 * @n: The index number. | |
| 250 * | |
| 251 * Gets a #JsonNode value from a parent #JsonNode by index. The | |
| 252 * returned #JsonNode should not be freed. | |
| 253 * | |
| 254 * Return: The #JsonNode. | |
| 255 */ | |
| 256 JsonNode * | |
| 257 fb_json_node_get_nth(JsonNode *root, guint n); | |
| 258 | |
| 259 /** | |
| 260 * fb_json_node_get_arr: | |
| 261 * @root: The root #JsonNode. | |
| 262 * @expr: The #JsonPath expression. | |
| 263 * @error: The return location for the #GError or #NULL. | |
| 264 * | |
| 265 * Gets a new #JsonArray value from a parent #JsonNode with a #JsonPath | |
| 266 * expression. The returned #JsonArray should be freed with | |
| 267 * #json_array_unref() when no longer needed. | |
| 268 * | |
| 269 * Returns: The new #JsonArray. | |
| 270 */ | |
| 271 JsonArray * | |
| 272 fb_json_node_get_arr(JsonNode *root, const gchar *expr, GError **error); | |
| 273 | |
| 274 /** | |
| 275 * fb_json_node_get_bool: | |
| 276 * @root: The root #JsonNode. | |
| 277 * @expr: The #JsonPath expression. | |
| 278 * @error: The return location for the #GError or #NULL. | |
| 279 * | |
| 280 * Gets a boolean value from a parent #JsonNode with a #JsonPath | |
| 281 * expression. | |
| 282 * | |
| 283 * Returns: The boolean value. | |
| 284 */ | |
| 285 gboolean | |
| 286 fb_json_node_get_bool(JsonNode *root, const gchar *expr, GError **error); | |
| 287 | |
| 288 /** | |
| 289 * fb_json_node_get_dbl: | |
| 290 * @root: The root #JsonNode. | |
| 291 * @expr: The #JsonPath expression. | |
| 292 * @error: The return location for the #GError or #NULL. | |
| 293 * | |
| 294 * Gets a floating point value from a parent #JsonNode with a #JsonPath | |
| 295 * expression. | |
| 296 * | |
| 297 * Returns: The floating point value. | |
| 298 */ | |
| 299 gdouble | |
| 300 fb_json_node_get_dbl(JsonNode *root, const gchar *expr, GError **error); | |
| 301 | |
| 302 /** | |
| 303 * fb_json_node_get_int: | |
| 304 * @root: The root #JsonNode. | |
| 305 * @expr: The #JsonPath expression. | |
| 306 * @error: The return location for the #GError or #NULL. | |
| 307 * | |
| 308 * Gets an integer value from a parent #JsonNode with a #JsonPath | |
| 309 * expression. | |
| 310 * | |
| 311 * Returns: The integer value. | |
| 312 */ | |
| 313 gint64 | |
| 314 fb_json_node_get_int(JsonNode *root, const gchar *expr, GError **error); | |
| 315 | |
| 316 /** | |
| 317 * fb_json_node_get_str: | |
| 318 * @root: The root #JsonNode. | |
| 319 * @expr: The #JsonPath expression. | |
| 320 * @error: The return location for the #GError or #NULL. | |
| 321 * | |
| 322 * Gets an string value from a parent #JsonNode with a #JsonPath | |
| 323 * expression. The returned string should be freed with #g_free() | |
| 324 * when no longer needed. | |
| 325 * | |
| 326 * Returns: The string value. | |
| 327 */ | |
| 328 gchar * | |
| 329 fb_json_node_get_str(JsonNode *root, const gchar *expr, GError **error); | |
| 330 | |
| 331 /** | |
| 332 * fb_json_values_new: | |
| 333 * @root: The root #JsonNode. | |
| 334 * | |
| 335 * Creates a new #FbJsonValues. The returned #FbJsonValues should be | |
| 336 * freed with #g_object_unref when no longer needed. | |
| 337 * | |
| 338 * Returns: The new #FbJsonValues. | |
| 339 */ | |
| 340 FbJsonValues * | |
| 341 fb_json_values_new(JsonNode *root); | |
| 342 | |
| 343 /** | |
| 344 * fb_json_values_add: | |
| 345 * @values: The #FbJsonValues. | |
| 346 * @type: The #FbJsonType. | |
| 347 * @required: #TRUE if the node is required, otherwise #FALSE. | |
| 348 * @expr: The #JsonPath expression. | |
| 349 * | |
| 350 * Adds a new #FbJsonValue to the #FbJsonValues. | |
| 351 */ | |
| 352 void | |
| 353 fb_json_values_add(FbJsonValues *values, FbJsonType type, gboolean required, | |
| 354 const gchar *expr); | |
| 355 | |
| 356 /** | |
| 357 * fb_json_values_get_root: | |
| 358 * @values: The #FbJsonValues. | |
| 359 * | |
| 360 * Gets the current working root #JsonNode. This is either the current | |
| 361 * array #JsonNode or the root #JsonNode. The returned #JsonNode should | |
| 362 * not be freed. | |
| 363 */ | |
| 364 JsonNode * | |
| 365 fb_json_values_get_root(FbJsonValues *values); | |
| 366 | |
| 367 /** | |
| 368 * fb_json_values_set_array: | |
| 369 * @values: The #FbJsonValues. | |
| 370 * @required: #TRUE if the node is required, otherwise #FALSE. | |
| 371 * @expr: The #JsonPath expression. | |
| 372 * | |
| 373 * Sets the #JsonPath for an array to base all #FbJsonValue's off. | |
| 374 */ | |
| 375 void | |
| 376 fb_json_values_set_array(FbJsonValues *values, gboolean required, | |
| 377 const gchar *expr); | |
| 378 | |
| 379 /** | |
| 380 * fb_json_values_update: | |
| 381 * @values: The #FbJsonValues. | |
| 382 * @error: The return location for the #GError or #NULL. | |
| 383 * | |
| 384 * Updates the current working root. This should be called after all of | |
| 385 * the #FbJsonValue's have been added with #fb_json_values_add(). If an | |
| 386 * array was set with #fb_json_values_set_array(), then this should be | |
| 387 * called in a while loop, until #FALSE is returned. | |
| 388 * | |
| 389 * Returns: #TRUE if the values were updated, otherwise #FALSE. | |
| 390 */ | |
| 391 gboolean | |
| 392 fb_json_values_update(FbJsonValues *values, GError **error); | |
| 393 | |
| 394 /** | |
| 395 * fb_json_values_next: | |
| 396 * @values: The #FbJsonValues. | |
| 397 * | |
| 398 * Gets the next #GValue from the #FbJsonValues. Before calling this | |
| 399 * function, #fb_json_values_update() must be called. | |
| 400 * | |
| 401 * Returns: The #GValue. | |
| 402 */ | |
| 403 const GValue * | |
| 404 fb_json_values_next(FbJsonValues *values); | |
| 405 | |
| 406 /** | |
| 407 * fb_json_values_next_bool: | |
| 408 * @values: The #FbJsonValues. | |
| 409 * @defval: The default value. | |
| 410 * | |
| 411 * Gets the next boolean value from the #FbJsonValues. Before calling | |
| 412 * this function, #fb_json_values_update() must be called. | |
| 413 * | |
| 414 * Returns: The boolean value. | |
| 415 */ | |
| 416 gboolean | |
| 417 fb_json_values_next_bool(FbJsonValues *values, gboolean defval); | |
| 418 | |
| 419 /** | |
| 420 * fb_json_values_next_dbl: | |
| 421 * @values: The #FbJsonValues. | |
| 422 * @defval: The default value. | |
| 423 * | |
| 424 * Gets the next floating point value from the #FbJsonValues. Before | |
| 425 * calling this function, #fb_json_values_update() must be called. | |
| 426 * | |
| 427 * Returns: The floating point value. | |
| 428 */ | |
| 429 gdouble | |
| 430 fb_json_values_next_dbl(FbJsonValues *values, gdouble defval); | |
| 431 | |
| 432 /** | |
| 433 * fb_json_values_next_int: | |
| 434 * @values: The #FbJsonValues. | |
| 435 * @defval: The default value. | |
| 436 * | |
| 437 * Gets the next integer value from the #FbJsonValues. Before calling | |
| 438 * this function, #fb_json_values_update() must be called. | |
| 439 * | |
| 440 * Returns: The integer value. | |
| 441 */ | |
| 442 gint64 | |
| 443 fb_json_values_next_int(FbJsonValues *values, gint64 defval); | |
| 444 | |
| 445 /** | |
| 446 * fb_json_values_next_str: | |
| 447 * @values: The #FbJsonValues. | |
| 448 * @defval: The default value. | |
| 449 * | |
| 450 * Gets the next string value from the #FbJsonValues. Before calling | |
| 451 * this function, #fb_json_values_update() must be called. | |
| 452 * | |
| 453 * Returns: The string value. | |
| 454 */ | |
| 455 const gchar * | |
| 456 fb_json_values_next_str(FbJsonValues *values, const gchar *defval); | |
| 457 | |
| 458 /** | |
| 459 * fb_json_values_next_str_dup: | |
| 460 * @values: The #FbJsonValues. | |
| 461 * @defval: The default value. | |
| 462 * | |
| 463 * Gets the next duplicate string value from the #FbJsonValues. Before | |
| 464 * calling this function, #fb_json_values_update() must be called. | |
| 465 * | |
| 466 * Returns: The duplicate string value. | |
| 467 */ | |
| 468 gchar * | |
| 469 fb_json_values_next_str_dup(FbJsonValues *values, const gchar *defval); | |
| 470 | |
| 471 #endif /* PURPLE_FACEBOOK_JSON_H */ |
