json-glib-1.0/json-glib/json-gobject.h

0001 /* json-gobject.h - JSON GObject integration
0002  *
0003  * This file is part of JSON-GLib
0004  * Copyright (C) 2007  OpenedHand Ltd.
0005  * Copyright (C) 2009  Intel Corp.
0006  *
0007  * This library is free software; you can redistribute it and/or
0008  * modify it under the terms of the GNU Lesser General Public
0009  * License as published by the Free Software Foundation; either
0010  * version 2.1 of the License, or (at your option) any later version.
0011  *
0012  * This library is distributed in the hope that it will be useful,
0013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0015  * Lesser General Public License for more details.
0016  *
0017  * You should have received a copy of the GNU Lesser General Public
0018  * License along with this library. If not, see <http://www.gnu.org/licenses/>.
0019  *
0020  * Author:
0021  *   Emmanuele Bassi  <ebassi@linux.intel.com>
0022  */
0023
0024 #ifndef __JSON_GOBJECT_H__
0025 #define __JSON_GOBJECT_H__
0026
0027 #include <json-glib/json-types.h>
0028
0029 G_BEGIN_DECLS
0030
0031 #define JSON_TYPE_SERIALIZABLE                  (json_serializable_get_type ())
0032 #define JSON_SERIALIZABLE(obj)                  (G_TYPE_CHECK_INSTANCE_CAST ((obj), JSON_TYPE_SERIALIZABLE, JsonSerializable))
0033 #define JSON_IS_SERIALIZABLE(obj)               (G_TYPE_CHECK_INSTANCE_TYPE ((obj), JSON_TYPE_SERIALIZABLE))
0034 #define JSON_SERIALIZABLE_GET_IFACE(obj)        (G_TYPE_INSTANCE_GET_INTERFACE ((obj), JSON_TYPE_SERIALIZABLE, JsonSerializableIface))
0035
0036 typedef struct _JsonSerializable        JsonSerializable; /* dummy */
0037 typedef struct _JsonSerializableIface   JsonSerializableIface;
0038
0039 /**
0040  * JsonSerializableIface:
0041  * @serialize_property: virtual function for serializing an object property
0042  *   into JSON
0043  * @deserialize_property: virtual function for deserializing JSON
0044  *   into an object property
0045  * @find_property: virtual function for finding a property definition using
0046  *   its name
0047  * @list_properties: virtual function for listing the installed property
0048  *   definitions
0049  * @set_property: virtual function for setting a property
0050  * @get_property: virtual function for getting a property
0051  *
0052  * Interface that allows serializing and deserializing object instances
0053  * with properties storing complex data types.
0054  *
0055  * The [func@Json.gobject_from_data] and [func@Json.gobject_to_data]
0056  * functions will check if the passed object type implements this interface,
0057  * so it can also be used to override the default property serialization
0058  * sequence.
0059  */
0060 struct _JsonSerializableIface
0061 {
0062   /*< private >*/
0063   GTypeInterface g_iface;
0064
0065   /*< public >*/
0066   JsonNode *(* serialize_property)   (JsonSerializable *serializable,
0067                                       const gchar      *property_name,
0068                                       const GValue     *value,
0069                                       GParamSpec       *pspec);
0070   gboolean  (* deserialize_property) (JsonSerializable *serializable,
0071                                       const gchar      *property_name,
0072                                       GValue           *value,
0073                                       GParamSpec       *pspec,
0074                                       JsonNode         *property_node);
0075
0076   GParamSpec * (* find_property)       (JsonSerializable *serializable,
0077                                         const char       *name);
0078   GParamSpec **(* list_properties)     (JsonSerializable *serializable,
0079                                         guint            *n_pspecs);
0080   void         (* set_property)        (JsonSerializable *serializable,
0081                                         GParamSpec       *pspec,
0082                                         const GValue     *value);
0083   void         (* get_property)        (JsonSerializable *serializable,
0084                                         GParamSpec       *pspec,
0085                                         GValue           *value);
0086 };
0087
0088 JSON_AVAILABLE_IN_1_0
0089 GType json_serializable_get_type (void) G_GNUC_CONST;
0090
0091 JSON_AVAILABLE_IN_1_0
0092 JsonNode *json_serializable_serialize_property           (JsonSerializable *serializable,
0093                                                           const gchar      *property_name,
0094                                                           const GValue     *value,
0095                                                           GParamSpec       *pspec);
0096 JSON_AVAILABLE_IN_1_0
0097 gboolean  json_serializable_deserialize_property         (JsonSerializable *serializable,
0098                                                           const gchar      *property_name,
0099                                                           GValue           *value,
0100                                                           GParamSpec       *pspec,
0101                                                           JsonNode         *property_node);
0102
0103 JSON_AVAILABLE_IN_1_0
0104 GParamSpec *    json_serializable_find_property         (JsonSerializable *serializable,
0105                                                          const char       *name);
0106 JSON_AVAILABLE_IN_1_0
0107 GParamSpec **   json_serializable_list_properties       (JsonSerializable *serializable,
0108                                                          guint            *n_pspecs);
0109 JSON_AVAILABLE_IN_1_0
0110 void            json_serializable_set_property          (JsonSerializable *serializable,
0111                                                          GParamSpec       *pspec,
0112                                                          const GValue     *value);
0113 JSON_AVAILABLE_IN_1_0
0114 void            json_serializable_get_property          (JsonSerializable *serializable,
0115                                                          GParamSpec       *pspec,
0116                                                          GValue           *value);
0117
0118 JSON_AVAILABLE_IN_1_0
0119 JsonNode *json_serializable_default_serialize_property   (JsonSerializable *serializable,
0120                                                           const gchar      *property_name,
0121                                                           const GValue     *value,
0122                                                           GParamSpec       *pspec);
0123 JSON_AVAILABLE_IN_1_0
0124 gboolean  json_serializable_default_deserialize_property (JsonSerializable *serializable,
0125                                                           const gchar      *property_name,
0126                                                           GValue           *value,
0127                                                           GParamSpec       *pspec,
0128                                                           JsonNode         *property_node);
0129
0130 /**
0131  * JsonBoxedSerializeFunc:
0132  * @boxed: a boxed data structure
0133  *
0134  * Serializes the passed `GBoxed` and stores it inside a `JsonNode`, for instance:
0135  *
0136  * ```c
0137  * static JsonNode *
0138  * my_point_serialize (gconstpointer boxed)
0139  * {
0140  *   const MyPoint *point = boxed;
0141  *
0142  *   g_autoptr(JsonBuilder) builder = json_builder_new ();
0143  *
0144  *   json_builder_begin_object (builder);
0145  *   json_builder_set_member_name (builder, "x");
0146  *   json_builder_add_double_value (builder, point->x);
0147  *   json_builder_set_member_name (builder, "y");
0148  *   json_builder_add_double_value (builder, point->y);
0149  *   json_builder_end_object (builder);
0150  *
0151  *   return json_builder_get_root (builder);
0152  * }
0153  * ```
0154  *
0155  * Return value: the newly created JSON node tree representing the boxed data
0156  *
0157  * Since: 0.10
0158  */
0159 typedef JsonNode *(* JsonBoxedSerializeFunc) (gconstpointer boxed);
0160
0161 /**
0162  * JsonBoxedDeserializeFunc:
0163  * @node: a node tree representing a boxed data
0164  *
0165  * Deserializes the contents of the passed `JsonNode` into a `GBoxed`, for instance:
0166  *
0167  * ```c
0168  * static gpointer
0169  * my_point_deserialize (JsonNode *node)
0170  * {
0171  *   double x = 0.0, y = 0.0;
0172  *
0173  *   if (JSON_NODE_HOLDS_ARRAY (node))
0174  *     {
0175  *       JsonArray *array = json_node_get_array (node);
0176  *
0177  *       if (json_array_get_length (array) == 2)
0178  *         {
0179  *           x = json_array_get_double_element (array, 0);
0180  *           y = json_array_get_double_element (array, 1);
0181  *         }
0182  *     }
0183  *   else if (JSON_NODE_HOLDS_OBJECT (node))
0184  *     {
0185  *       JsonObject *obj = json_node_get_object (node);
0186  *
0187  *       x = json_object_get_double_member_with_default (obj, "x", 0.0);
0188  *       y = json_object_get_double_member_with_default (obj, "y", 0.0);
0189  *     }
0190  *
0191  *   // my_point_new() is defined elsewhere
0192  *   return my_point_new (x, y);
0193  * }
0194  * ```
0195  *
0196  * Return value: the newly created boxed structure
0197  *
0198  * Since: 0.10
0199  */
0200 typedef gpointer (* JsonBoxedDeserializeFunc) (JsonNode *node);
0201
0202 JSON_AVAILABLE_IN_1_0
0203 void      json_boxed_register_serialize_func   (GType                    gboxed_type,
0204                                                 JsonNodeType             node_type,
0205                                                 JsonBoxedSerializeFunc   serialize_func);
0206 JSON_AVAILABLE_IN_1_0
0207 void      json_boxed_register_deserialize_func (GType                    gboxed_type,
0208                                                 JsonNodeType             node_type,
0209                                                 JsonBoxedDeserializeFunc deserialize_func);
0210 JSON_AVAILABLE_IN_1_0
0211 gboolean  json_boxed_can_serialize             (GType                    gboxed_type,
0212                                                 JsonNodeType            *node_type);
0213 JSON_AVAILABLE_IN_1_0
0214 gboolean  json_boxed_can_deserialize           (GType                    gboxed_type,
0215                                                 JsonNodeType             node_type);
0216 JSON_AVAILABLE_IN_1_0
0217 JsonNode *json_boxed_serialize                 (GType                    gboxed_type,
0218                                                 gconstpointer            boxed);
0219 JSON_AVAILABLE_IN_1_0
0220 gpointer  json_boxed_deserialize               (GType                    gboxed_type,
0221                                                 JsonNode                *node);
0222
0223 JSON_AVAILABLE_IN_1_0
0224 JsonNode *json_gobject_serialize               (GObject                 *gobject);
0225 JSON_AVAILABLE_IN_1_0
0226 GObject * json_gobject_deserialize             (GType                    gtype,
0227                                                 JsonNode                *node);
0228
0229 JSON_AVAILABLE_IN_1_0
0230 GObject * json_gobject_from_data               (GType                    gtype,
0231                                                 const gchar             *data,
0232                                                 gssize                   length,
0233                                                 GError                 **error);
0234 JSON_AVAILABLE_IN_1_0
0235 gchar *   json_gobject_to_data                 (GObject                 *gobject,
0236                                                 gsize                   *length);
0237
0238 JSON_DEPRECATED_IN_1_0_FOR(json_gobject_from_data)
0239 GObject * json_construct_gobject               (GType                    gtype,
0240                                                 const gchar             *data,
0241                                                 gsize                    length,
0242                                                 GError                 **error);
0243 JSON_DEPRECATED_IN_1_0_FOR(json_gobject_to_data)
0244 gchar *   json_serialize_gobject               (GObject                 *gobject,
0245                                                 gsize                   *length) G_GNUC_MALLOC;
0246
0247 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
0248 G_DEFINE_AUTOPTR_CLEANUP_FUNC (JsonSerializable, g_object_unref)
0249 #endif
0250
0251 G_END_DECLS
0252
0253 #endif /* __JSON_GOBJECT_H__ */