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