json-glib/json-types.h

   1 /* json-types.h - JSON data types
   2  *
   3  * This file is part of JSON-GLib
   4  * Copyright (C) 2007  OpenedHand Ltd.
   5  * Copyright (C) 2009  Intel Corp.
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2.1 of the License, or (at your option) any later version.
  11  *
  12  * This library 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 GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General Public
  18  * License along with this library. If not, see <http://www.gnu.org/licenses/>.
  19  *
  20  * Author:
  21  *   Emmanuele Bassi  <ebassi@linux.intel.com>
  22  */
  23
  24 #if !defined(__JSON_GLIB_INSIDE__) && !defined(JSON_COMPILATION)
  25 #error "Only <json-glib/json-glib.h> can be included directly."
  26 #endif
  27
  28 #ifndef __JSON_TYPES_H__
  29 #define __JSON_TYPES_H__
  30
  31 #include <glib-object.h>
  32
  33 G_BEGIN_DECLS
  34
  35 /**
  36  * JSON_NODE_TYPE:
  37  * @node: a #JsonNode
  38  *
  39  * Evaluates to the #JsonNodeType contained by @node
  40  */
  41 #define JSON_NODE_TYPE(node)    (json_node_get_node_type ((node)))
  42
  43 /**
  44  * JSON_NODE_HOLDS:
  45  * @node: a #JsonNode
  46  * @t: a #JsonNodeType
  47  *
  48  * Evaluates to %TRUE if the @node holds type @t
  49  *
  50  * Since: 0.10
  51  */
  52 #define JSON_NODE_HOLDS(node,t)         (json_node_get_node_type ((node)) == (t))
  53
  54 /**
  55  * JSON_NODE_HOLDS_VALUE:
  56  * @node: a #JsonNode
  57  *
  58  * Evaluates to %TRUE if @node holds a %JSON_NODE_VALUE
  59  *
  60  * Since: 0.10
  61  */
  62 #define JSON_NODE_HOLDS_VALUE(node)     (JSON_NODE_HOLDS ((node), JSON_NODE_VALUE))
  63
  64 /**
  65  * JSON_NODE_HOLDS_OBJECT:
  66  * @node: a #JsonNode
  67  *
  68  * Evaluates to %TRUE if @node holds a %JSON_NODE_OBJECT
  69  *
  70  * Since: 0.10
  71  */
  72 #define JSON_NODE_HOLDS_OBJECT(node)    (JSON_NODE_HOLDS ((node), JSON_NODE_OBJECT))
  73
  74 /**
  75  * JSON_NODE_HOLDS_ARRAY:
  76  * @node: a #JsonNode
  77  *
  78  * Evaluates to %TRUE if @node holds a %JSON_NODE_ARRAY
  79  *
  80  * Since: 0.10
  81  */
  82 #define JSON_NODE_HOLDS_ARRAY(node)     (JSON_NODE_HOLDS ((node), JSON_NODE_ARRAY))
  83
  84 /**
  85  * JSON_NODE_HOLDS_NULL:
  86  * @node: a #JsonNode
  87  *
  88  * Evaluates to %TRUE if @node holds a %JSON_NODE_NULL
  89  *
  90  * Since: 0.10
  91  */
  92 #define JSON_NODE_HOLDS_NULL(node)      (JSON_NODE_HOLDS ((node), JSON_NODE_NULL))
  93
  94 #define JSON_TYPE_NODE          (json_node_get_type ())
  95 #define JSON_TYPE_OBJECT        (json_object_get_type ())
  96 #define JSON_TYPE_ARRAY         (json_array_get_type ())
  97
  98 /**
  99  * JsonNode:
 100  * @type: the type of node
 101  *
 102  * A generic container of JSON data types. The contents of the #JsonNode
 103  * structure are private and should only be accessed via the provided
 104  * functions and never directly.
 105  */
 106 typedef struct _JsonNode        JsonNode;
 107
 108 /**
 109  * JsonObject:
 110  *
 111  * A JSON object type. The contents of the #JsonObject structure are private
 112  * and should only be accessed by the provided API
 113  */
 114 typedef struct _JsonObject      JsonObject;
 115
 116 /**
 117  * JsonArray:
 118  *
 119  * A JSON array type. The contents of the #JsonArray structure are private
 120  * and should only be accessed by the provided API
 121  */
 122 typedef struct _JsonArray       JsonArray;
 123
 124 /**
 125  * JsonNodeType:
 126  * @JSON_NODE_OBJECT: The node contains a #JsonObject
 127  * @JSON_NODE_ARRAY: The node contains a #JsonArray
 128  * @JSON_NODE_VALUE: The node contains a fundamental type
 129  * @JSON_NODE_NULL: Special type, for nodes containing null
 130  *
 131  * Indicates the content of a #JsonNode.
 132  */
 133 typedef enum {
 134   JSON_NODE_OBJECT,
 135   JSON_NODE_ARRAY,
 136   JSON_NODE_VALUE,
 137   JSON_NODE_NULL
 138 } JsonNodeType;
 139
 140 /**
 141  * JsonObjectForeach:
 142  * @object: the iterated #JsonObject
 143  * @member_name: the name of the member
 144  * @member_node: a #JsonNode containing the @member_name value
 145  * @user_data: data passed to the function
 146  *
 147  * The function to be passed to json_object_foreach_member(). You
 148  * should not add or remove members to and from @object within
 149  * this function. It is safe to change the value of @member_node.
 150  *
 151  * Since: 0.8
 152  */
 153 typedef void (* JsonObjectForeach) (JsonObject  *object,
 154                                     const gchar *member_name,
 155                                     JsonNode    *member_node,
 156                                     gpointer     user_data);
 157
 158 /**
 159  * JsonArrayForeach:
 160  * @array: the iterated #JsonArray
 161  * @index_: the index of the element
 162  * @element_node: a #JsonNode containing the value at @index_
 163  * @user_data: data passed to the function
 164  *
 165  * The function to be passed to json_array_foreach_element(). You
 166  * should not add or remove elements to and from @array within
 167  * this function. It is safe to change the value of @element_node.
 168  *
 169  * Since: 0.8
 170  */
 171 typedef void (* JsonArrayForeach) (JsonArray  *array,
 172                                    guint       index_,
 173                                    JsonNode   *element_node,
 174                                    gpointer    user_data);
 175
 176
 177
 178 /*
 179  * JsonNode
 180  */
 181 GType                 json_node_get_type        (void) G_GNUC_CONST;
 182 JsonNode *            json_node_new             (JsonNodeType  type);
 183 JsonNode *            json_node_copy            (JsonNode     *node);
 184 void                  json_node_free            (JsonNode     *node);
 185 JsonNodeType          json_node_get_node_type   (JsonNode     *node);
 186 GType                 json_node_get_value_type  (JsonNode     *node);
 187 void                  json_node_set_parent      (JsonNode     *node,
 188                                                  JsonNode     *parent);
 189 JsonNode *            json_node_get_parent      (JsonNode     *node);
 190 #if !GLIB_CHECK_VERSION(2,31,0)
 191 G_CONST_RETURN gchar *json_node_type_name       (JsonNode     *node);
 192 #else
 193 const gchar *json_node_type_name       (JsonNode     *node);
 194 #endif
 195 void                  json_node_set_object      (JsonNode     *node,
 196                                                  JsonObject   *object);
 197 void                  json_node_take_object     (JsonNode     *node,
 198                                                  JsonObject   *object);
 199 JsonObject *          json_node_get_object      (JsonNode     *node);
 200 JsonObject *          json_node_dup_object      (JsonNode     *node);
 201 void                  json_node_set_array       (JsonNode     *node,
 202                                                  JsonArray    *array);
 203 void                  json_node_take_array      (JsonNode     *node,
 204                                                  JsonArray    *array);
 205 JsonArray *           json_node_get_array       (JsonNode     *node);
 206 JsonArray *           json_node_dup_array       (JsonNode     *node);
 207 void                  json_node_set_value       (JsonNode     *node,
 208                                                  const GValue *value);
 209 void                  json_node_get_value       (JsonNode     *node,
 210                                                  GValue       *value);
 211 void                  json_node_set_string      (JsonNode     *node,
 212                                                  const gchar  *value);
 213 #if !GLIB_CHECK_VERSION(2,31,0)
 214 G_CONST_RETURN gchar *json_node_get_string      (JsonNode     *node);
 215 #else
 216 const gchar *json_node_get_string      (JsonNode     *node);
 217 #endif
 218 gchar *               json_node_dup_string      (JsonNode     *node);
 219 void                  json_node_set_int         (JsonNode     *node,
 220                                                  gint64        value);
 221 gint64                json_node_get_int         (JsonNode     *node);
 222 void                  json_node_set_double      (JsonNode     *node,
 223                                                  gdouble       value);
 224 gdouble               json_node_get_double      (JsonNode     *node);
 225 void                  json_node_set_boolean     (JsonNode     *node,
 226                                                  gboolean      value);
 227 gboolean              json_node_get_boolean     (JsonNode     *node);
 228 gboolean              json_node_is_null         (JsonNode     *node);
 229
 230 /*
 231  * JsonObject
 232  */
 233 GType                 json_object_get_type           (void) G_GNUC_CONST;
 234 JsonObject *          json_object_new                (void);
 235 JsonObject *          json_object_ref                (JsonObject  *object);
 236 void                  json_object_unref              (JsonObject  *object);
 237
 238 #ifndef JSON_DISABLE_DEPRECATED
 239 void                  json_object_add_member         (JsonObject  *object,
 240                                                       const gchar *member_name,
 241                                                       JsonNode    *node) G_GNUC_DEPRECATED;
 242 #endif /* JSON_DISABLE_DEPRECATED */
 243
 244 void                  json_object_set_member         (JsonObject  *object,
 245                                                       const gchar *member_name,
 246                                                       JsonNode    *node);
 247 void                  json_object_set_int_member     (JsonObject  *object,
 248                                                       const gchar *member_name,
 249                                                       gint64       value);
 250 void                  json_object_set_double_member  (JsonObject  *object,
 251                                                       const gchar *member_name,
 252                                                       gdouble      value);
 253 void                  json_object_set_boolean_member (JsonObject  *object,
 254                                                       const gchar *member_name,
 255                                                       gboolean     value);
 256 void                  json_object_set_string_member  (JsonObject  *object,
 257                                                       const gchar *member_name,
 258                                                       const gchar *value);
 259 void                  json_object_set_null_member    (JsonObject  *object,
 260                                                       const gchar *member_name);
 261 void                  json_object_set_array_member   (JsonObject  *object,
 262                                                       const gchar *member_name,
 263                                                       JsonArray   *value);
 264 void                  json_object_set_object_member  (JsonObject  *object,
 265                                                       const gchar *member_name,
 266                                                       JsonObject  *value);
 267 GList *               json_object_get_members        (JsonObject  *object);
 268 JsonNode *            json_object_get_member         (JsonObject  *object,
 269                                                       const gchar *member_name);
 270 JsonNode *            json_object_dup_member         (JsonObject  *object,
 271                                                       const gchar *member_name);
 272 gint64                json_object_get_int_member     (JsonObject  *object,
 273                                                       const gchar *member_name);
 274 gdouble               json_object_get_double_member  (JsonObject  *object,
 275                                                       const gchar *member_name);
 276 gboolean              json_object_get_boolean_member (JsonObject  *object,
 277                                                       const gchar *member_name);
 278 #if !GLIB_CHECK_VERSION(2,31,0)
 279 G_CONST_RETURN gchar *json_object_get_string_member  (JsonObject  *object,
 280                                                       const gchar *member_name);
 281 #else
 282 const gchar *json_object_get_string_member  (JsonObject  *object,
 283                                                       const gchar *member_name);
 284 #endif
 285 gboolean              json_object_get_null_member    (JsonObject  *object,
 286                                                       const gchar *member_name);
 287 JsonArray *           json_object_get_array_member   (JsonObject  *object,
 288                                                       const gchar *member_name);
 289 JsonObject *          json_object_get_object_member  (JsonObject  *object,
 290                                                       const gchar *member_name);
 291 gboolean              json_object_has_member         (JsonObject  *object,
 292                                                       const gchar *member_name);
 293 void                  json_object_remove_member      (JsonObject  *object,
 294                                                       const gchar *member_name);
 295 GList *               json_object_get_values         (JsonObject  *object);
 296 guint                 json_object_get_size           (JsonObject  *object);
 297 void                  json_object_foreach_member     (JsonObject  *object,
 298                                                       JsonObjectForeach func,
 299                                                       gpointer     data);
 300
 301 GType                 json_array_get_type            (void) G_GNUC_CONST;
 302 JsonArray *           json_array_new                 (void);
 303 JsonArray *           json_array_sized_new           (guint        n_elements);
 304 JsonArray *           json_array_ref                 (JsonArray   *array);
 305 void                  json_array_unref               (JsonArray   *array);
 306 void                  json_array_add_element         (JsonArray   *array,
 307                                                       JsonNode    *node);
 308 void                  json_array_add_int_element     (JsonArray   *array,
 309                                                       gint64       value);
 310 void                  json_array_add_double_element  (JsonArray   *array,
 311                                                       gdouble      value);
 312 void                  json_array_add_boolean_element (JsonArray   *array,
 313                                                       gboolean     value);
 314 void                  json_array_add_string_element  (JsonArray   *array,
 315                                                       const gchar *value);
 316 void                  json_array_add_null_element    (JsonArray   *array);
 317 void                  json_array_add_array_element   (JsonArray   *array,
 318                                                       JsonArray   *value);
 319 void                  json_array_add_object_element  (JsonArray   *array,
 320                                                       JsonObject  *value);
 321 GList *               json_array_get_elements        (JsonArray   *array);
 322 JsonNode *            json_array_get_element         (JsonArray   *array,
 323                                                       guint        index_);
 324 gint64                json_array_get_int_element     (JsonArray   *array,
 325                                                       guint        index_);
 326 gdouble               json_array_get_double_element  (JsonArray   *array,
 327                                                       guint        index_);
 328 gboolean              json_array_get_boolean_element (JsonArray   *array,
 329                                                       guint        index_);
 330 #if !GLIB_CHECK_VERSION(2,31,0)
 331 G_CONST_RETURN gchar *json_array_get_string_element  (JsonArray   *array,
 332                                                       guint        index_);
 333 #else
 334 const gchar *json_array_get_string_element  (JsonArray   *array,
 335                                                       guint        index_);
 336 #endif
 337 gboolean              json_array_get_null_element    (JsonArray   *array,
 338                                                       guint        index_);
 339 JsonArray *           json_array_get_array_element   (JsonArray   *array,
 340                                                       guint        index_);
 341 JsonObject *          json_array_get_object_element  (JsonArray   *array,
 342                                                       guint        index_);
 343 JsonNode *            json_array_dup_element         (JsonArray   *array,
 344                                                       guint        index_);
 345 void                  json_array_remove_element      (JsonArray   *array,
 346                                                       guint        index_);
 347 guint                 json_array_get_length          (JsonArray   *array);
 348 void                  json_array_foreach_element     (JsonArray   *array,
 349                                                       JsonArrayForeach func,
 350                                                       gpointer     data);
 351
 352 G_END_DECLS
 353
 354 #endif /* __JSON_TYPES_H__ */