json-gobject.h 11.1 KB
Newer Older
1
2
3
4
/* json-gobject.h - JSON GObject integration
 * 
 * This file is part of JSON-GLib
 * Copyright (C) 2007  OpenedHand Ltd.
5
 * Copyright (C) 2009  Intel Corp.
6
7
8
9
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * 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
13
14
15
16
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
17
18
19
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
 *
20
 * Author:
21
 *   Emmanuele Bassi  <ebassi@linux.intel.com>
22
23
24
25
26
27
28
29
30
 */

#ifndef __JSON_GOBJECT_H__
#define __JSON_GOBJECT_H__

#include <json-glib/json-types.h>

G_BEGIN_DECLS

31
32
33
34
35
36
37
38
39
40
#define JSON_TYPE_SERIALIZABLE                  (json_serializable_get_type ())
#define JSON_SERIALIZABLE(obj)                  (G_TYPE_CHECK_INSTANCE_CAST ((obj), JSON_TYPE_SERIALIZABLE, JsonSerializable))
#define JSON_IS_SERIALIZABLE(obj)               (G_TYPE_CHECK_INSTANCE_TYPE ((obj), JSON_TYPE_SERIALIZABLE))
#define JSON_SERIALIZABLE_GET_IFACE(obj)        (G_TYPE_INSTANCE_GET_INTERFACE ((obj), JSON_TYPE_SERIALIZABLE, JsonSerializableIface))

typedef struct _JsonSerializable        JsonSerializable; /* dummy */
typedef struct _JsonSerializableIface   JsonSerializableIface;

/**
 * JsonSerializableIface:
41
42
43
44
 * @serialize_property: virtual function for serializing an object property
 *   into JSON
 * @deserialize_property: virtual function for deserializing JSON
 *   into an object property
45
46
47
48
49
50
 * @find_property: virtual function for finding a property definition using
 *   its name
 * @list_properties: virtual function for listing the installed property
 *   definitions
 * @set_property: virtual function for setting a property
 * @get_property: virtual function for getting a property
51
 *
52
53
54
55
56
 * Interface that allows serializing and deserializing object instances
 * with properties storing complex data types.
 *
 * The [func@Json.gobject_from_data] and [func@Json.gobject_to_data]
 * functions will check if the passed object type implements this interface,
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
 * so it can also be used to override the default property serialization
 * sequence.
 */
struct _JsonSerializableIface
{
  /*< private >*/
  GTypeInterface g_iface;

  /*< public >*/
  JsonNode *(* serialize_property)   (JsonSerializable *serializable,
                                      const gchar      *property_name,
                                      const GValue     *value,
                                      GParamSpec       *pspec);
  gboolean  (* deserialize_property) (JsonSerializable *serializable,
                                      const gchar      *property_name,
                                      GValue           *value,
                                      GParamSpec       *pspec,
                                      JsonNode         *property_node);
75
76
77
78
79
80
81
82
83
84
85

  GParamSpec * (* find_property)       (JsonSerializable *serializable,
                                        const char       *name);
  GParamSpec **(* list_properties)     (JsonSerializable *serializable,
                                        guint            *n_pspecs);
  void         (* set_property)        (JsonSerializable *serializable,
                                        GParamSpec       *pspec,
                                        const GValue     *value);
  void         (* get_property)        (JsonSerializable *serializable,
                                        GParamSpec       *pspec,
                                        GValue           *value);
86
87
};

88
89
JSON_AVAILABLE_IN_1_0
GType json_serializable_get_type (void) G_GNUC_CONST;
90

91
JSON_AVAILABLE_IN_1_0
92
93
94
95
JsonNode *json_serializable_serialize_property           (JsonSerializable *serializable,
                                                          const gchar      *property_name,
                                                          const GValue     *value,
                                                          GParamSpec       *pspec);
96
JSON_AVAILABLE_IN_1_0
97
98
99
100
101
102
gboolean  json_serializable_deserialize_property         (JsonSerializable *serializable,
                                                          const gchar      *property_name,
                                                          GValue           *value,
                                                          GParamSpec       *pspec,
                                                          JsonNode         *property_node);

103
JSON_AVAILABLE_IN_1_0
104
105
GParamSpec *    json_serializable_find_property         (JsonSerializable *serializable,
                                                         const char       *name);
106
JSON_AVAILABLE_IN_1_0
107
108
GParamSpec **   json_serializable_list_properties       (JsonSerializable *serializable,
                                                         guint            *n_pspecs);
109
JSON_AVAILABLE_IN_1_0
110
111
112
void            json_serializable_set_property          (JsonSerializable *serializable,
                                                         GParamSpec       *pspec,
                                                         const GValue     *value);
113
JSON_AVAILABLE_IN_1_0
114
115
116
117
void            json_serializable_get_property          (JsonSerializable *serializable,
                                                         GParamSpec       *pspec,
                                                         GValue           *value);

118
JSON_AVAILABLE_IN_1_0
119
120
121
122
JsonNode *json_serializable_default_serialize_property   (JsonSerializable *serializable,
                                                          const gchar      *property_name,
                                                          const GValue     *value,
                                                          GParamSpec       *pspec);
123
JSON_AVAILABLE_IN_1_0
124
125
126
127
128
gboolean  json_serializable_default_deserialize_property (JsonSerializable *serializable,
                                                          const gchar      *property_name,
                                                          GValue           *value,
                                                          GParamSpec       *pspec,
                                                          JsonNode         *property_node);
129

130
131
/**
 * JsonBoxedSerializeFunc:
132
 * @boxed: a boxed data structure
133
 *
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
 * Serializes the passed `GBoxed` and stores it inside a `JsonNode`, for instance:
 *
 * ```c
 * static JsonNode *
 * my_point_serialize (gconstpointer boxed)
 * {
 *   const MyPoint *point = boxed;
 *
 *   g_autoptr(JsonBuilder) builder = json_builder_new ();
 *
 *   json_builder_begin_object (builder);
 *   json_builder_set_member_name (builder, "x");
 *   json_builder_add_double_value (builder, point->x);
 *   json_builder_set_member_name (builder, "y");
 *   json_builder_add_double_value (builder, point->y);
 *   json_builder_end_object (builder);
 *
 *   return json_builder_get_root (builder);
 * }
 * ```
154
 *
155
 * Return value: the newly created JSON node tree representing the boxed data
156
157
158
159
160
161
162
 *
 * Since: 0.10
 */
typedef JsonNode *(* JsonBoxedSerializeFunc) (gconstpointer boxed);

/**
 * JsonBoxedDeserializeFunc:
163
 * @node: a node tree representing a boxed data
164
 *
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
 * Deserializes the contents of the passed `JsonNode` into a `GBoxed`, for instance:
 *
 * ```c
 * static gpointer
 * my_point_deserialize (JsonNode *node)
 * {
 *   double x = 0.0, y = 0.0;
 *
 *   if (JSON_NODE_HOLDS_ARRAY (node))
 *     {
 *       JsonArray *array = json_node_get_array (node);
 *
 *       if (json_array_get_length (array) == 2)
 *         {
 *           x = json_array_get_double_element (array, 0);
 *           y = json_array_get_double_element (array, 1);
 *         }
 *     }
 *   else if (JSON_NODE_HOLDS_OBJECT (node))
 *     {
 *       JsonObject *obj = json_node_get_object (node);
 *
 *       x = json_object_get_double_member_with_default (obj, "x", 0.0);
 *       y = json_object_get_double_member_with_default (obj, "y", 0.0);
 *     }
 *
 *   // my_point_new() is defined elsewhere
 *   return my_point_new (x, y);
 * }
 * ```
195
 *
196
 * Return value: the newly created boxed structure
197
198
199
200
201
 *
 * Since: 0.10
 */
typedef gpointer (* JsonBoxedDeserializeFunc) (JsonNode *node);

202
JSON_AVAILABLE_IN_1_0
203
204
205
void      json_boxed_register_serialize_func   (GType                    gboxed_type,
                                                JsonNodeType             node_type,
                                                JsonBoxedSerializeFunc   serialize_func);
206
JSON_AVAILABLE_IN_1_0
207
208
void      json_boxed_register_deserialize_func (GType                    gboxed_type,
                                                JsonNodeType             node_type,
209
                                                JsonBoxedDeserializeFunc deserialize_func);
210
JSON_AVAILABLE_IN_1_0
211
212
gboolean  json_boxed_can_serialize             (GType                    gboxed_type,
                                                JsonNodeType            *node_type);
213
JSON_AVAILABLE_IN_1_0
214
215
gboolean  json_boxed_can_deserialize           (GType                    gboxed_type,
                                                JsonNodeType             node_type);
216
JSON_AVAILABLE_IN_1_0
217
218
JsonNode *json_boxed_serialize                 (GType                    gboxed_type,
                                                gconstpointer            boxed);
219
JSON_AVAILABLE_IN_1_0
220
221
222
gpointer  json_boxed_deserialize               (GType                    gboxed_type,
                                                JsonNode                *node);

223
JSON_AVAILABLE_IN_1_0
224
JsonNode *json_gobject_serialize               (GObject                 *gobject);
225
JSON_AVAILABLE_IN_1_0
226
227
228
GObject * json_gobject_deserialize             (GType                    gtype,
                                                JsonNode                *node);

229
JSON_AVAILABLE_IN_1_0
230
231
232
233
GObject * json_gobject_from_data               (GType                    gtype,
                                                const gchar             *data,
                                                gssize                   length,
                                                GError                 **error);
234
JSON_AVAILABLE_IN_1_0
235
236
gchar *   json_gobject_to_data                 (GObject                 *gobject,
                                                gsize                   *length);
237

238
JSON_DEPRECATED_IN_1_0_FOR(json_gobject_from_data)
239
240
241
GObject * json_construct_gobject               (GType                    gtype,
                                                const gchar             *data,
                                                gsize                    length,
242
                                                GError                 **error);
243
JSON_DEPRECATED_IN_1_0_FOR(json_gobject_to_data)
244
gchar *   json_serialize_gobject               (GObject                 *gobject,
245
                                                gsize                   *length) G_GNUC_MALLOC;
246

247
248
249
250
#ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
G_DEFINE_AUTOPTR_CLEANUP_FUNC (JsonSerializable, g_object_unref)
#endif

251
252
253
G_END_DECLS

#endif /* __JSON_GOBJECT_H__ */