libpurple/protocols/facebook/json.h

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