1/* -*- mode: C; c-basic-offset: 4; indent-tabs-mode: nil; -*- */
2/* vim:set et sts=4: */
3/* ibus - The Input Bus
4 * Copyright (C) 2008-2013 Peng Huang <shawn.p.huang@gmail.com>
5 * Copyright (C) 2018 Takao Fujiwara <takao.fujiwara1@gmail.com>
6 * Copyright (C) 2008-2018 Red Hat, Inc.
7 *
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License as published by the Free Software Foundation; either
11 * version 2.1 of the License, or (at your option) any later version.
12 *
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
17 *
18 * You should have received a copy of the GNU Lesser General Public
19 * License along with this library; if not, write to the Free Software
20 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301
21 * USA
22 */
23
24#if !defined (__IBUS_H_INSIDE__) && !defined (IBUS_COMPILATION)
25#error "Only <ibus.h> can be included directly"
26#endif
27
28#ifndef __IBUS_SERIALIZABLE_H_
29#define __IBUS_SERIALIZABLE_H_
30
31/**
32 * SECTION: ibusserializable
33 * @short_description: A serializable object.
34 * @stability: Stable
35 *
36 * An #IBusSerializable is an IBus object which can be serialized, that is,
37 * to be to and from a #GVariant.
38 *
39 * This class is to be extended by other class that requires serialization.
40 * An extended class should overrides following methods:
41 * <itemizedlist>
42 * <listitem>
43 * <para><function>serialize(object,iter)</function>: for serialize.</para>
44 * </listitem>
45 * <listitem>
46 * <para><function>deserialize(object,iter)</function>: for deserialize.</para>
47 * </listitem>
48 * <listitem>
49 * <para><function>copy(desc,src)</function>: for copy between IBusSerializable.</para>
50 * </listitem>
51 * </itemizedlist>
52 * See IBusSerializableSerializeFunc(), IBusSerializableDeserializeFunc(), IBusSerializableCopyFunc()
53 * for function prototype.
54 */
55
56#include "ibusobject.h"
57
58/*
59 * Type macros.
60 */
61
62/* define IBusSerializable macros */
63#define IBUS_TYPE_SERIALIZABLE \
64 (ibus_serializable_get_type ())
65#define IBUS_SERIALIZABLE(obj) \
66 (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_SERIALIZABLE, IBusSerializable))
67#define IBUS_SERIALIZABLE_CLASS(klass) \
68 (G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_SERIALIZABLE, IBusSerializableClass))
69#define IBUS_IS_SERIALIZABLE(obj) \
70 (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_SERIALIZABLE))
71#define IBUS_IS_SERIALIZABLE_CLASS(klass) \
72 (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_SERIALIZABLE))
73#define IBUS_SERIALIZABLE_GET_CLASS(obj) \
74 (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_SERIALIZABLE, IBusSerializableClass))
75
76/**
77 * ibus_serializable_set_attachment:
78 * @o: An IBusSerializable.
79 * @k: String formatted key for indexing value.
80 * @v: Value to be attached. Should be also serializable.
81 *
82 * Attach a value to an IBusSerializable.
83 * This macro is an convenient wrapper of ibus_serializable_set_qattachment().
84 */
85#define ibus_serializable_set_attachment(o, k, v) \
86 ibus_serializable_set_qattachment (o, g_quark_from_string (k), v)
87
88/**
89 * ibus_serializable_get_attachment:
90 * @o: An #IBusSerializable.
91 * @k: String formatted key for indexing value.
92 *
93 * Get a value from attachment of an #IBusSerializable.
94 * This macro is an convenient wrapper of ibus_serializable_get_qattachment().
95 */
96#define ibus_serializable_get_attachment(o, k) \
97 ibus_serializable_get_qattachment (o, g_quark_from_string (k))
98
99/**
100 * ibus_serializable_remove_attachment:
101 * @o: An #IBusSerializable.
102 * @k: String formatted key for indexing value.
103 *
104 * Remove a value from attachment of an #IBusSerializable.
105 * This macro is an convenient wrapper of ibus_serializable_remove_qattachment().
106 */
107#define ibus_serializable_remove_attachment(o, k) \
108 ibus_serializable_remove_qattachment (o, g_quark_from_string (k))
109
110G_BEGIN_DECLS
111
112typedef struct _IBusSerializable IBusSerializable;
113typedef struct _IBusSerializableClass IBusSerializableClass;
114typedef struct _IBusSerializablePrivate IBusSerializablePrivate;
115
116/**
117 * IBusSerializable:
118 *
119 * All the fields in the <structname>IBusSerializable</structname> structure are
120 * private to the #IBusSerializable and should never be accessed directly.
121 */
122struct _IBusSerializable {
123 /*< private >*/
124 IBusObject parent;
125 IBusSerializablePrivate *priv;
126 /* instance members */
127};
128
129/**
130 * IBusSerializableSerializeFunc:
131 * @serializable: An #IBusSerializable.
132 * @builder: A #GVariantBuilder.
133 *
134 * Prototype of serialize function.
135 * Serialize function convert an #IBusSerializable to #GVariantBuilder.
136 * Returns a gboolean value which indicates whether the conversion is success.
137 * Return %TRUE if succeed.
138 *
139 * Returns: %TRUE if succeed; %FALSE otherwise.
140 */
141typedef gboolean (* IBusSerializableSerializeFunc) (IBusSerializable *serializable,
142 GVariantBuilder *builder);
143
144/**
145 * IBusSerializableDeserializeFunc:
146 * @serializable: An #IBusSerializable.
147 * @variant: A #GVariant contains a tuple.
148 *
149 * Prototype of deserialize function.
150 * Deserialize function convert a #GVariant to #IBusSerializable.
151 * Returns an integer value which indicates how many values in
152 * the variant(tuple) are consumed.
153 *
154 * Returns: The number of values in the variant(tuple) are consumed.
155 */
156typedef gint (* IBusSerializableDeserializeFunc) (IBusSerializable *serializable,
157 GVariant *variant);
158
159/**
160 * IBusSerializableCopyFunc:
161 * @dest: The destination #IBusSerializable.
162 * @src: A source #IBusSerializable.
163 *
164 * Prototype of copy function.
165 * Copy function copy from source #IBusSerializable to the destination one.
166 * Returns a gboolean value which indicates whether the copying is success.
167 *
168 * Returns: %TRUE if succeed; %FALSE otherwise.
169 */
170typedef gboolean (* IBusSerializableCopyFunc) (IBusSerializable *dest,
171 const IBusSerializable *src);
172struct _IBusSerializableClass {
173 /*< private >*/
174 IBusObjectClass parent;
175
176 /* virtual table */
177 gboolean (* serialize) (IBusSerializable *object,
178 GVariantBuilder *builder);
179 gint (* deserialize) (IBusSerializable *object,
180 GVariant *variant);
181 gboolean (* copy) (IBusSerializable *dest,
182 const IBusSerializable *src);
183 /*< private >*/
184 /* padding */
185 gpointer pdummy[5];
186};
187
188GType ibus_serializable_get_type (void);
189
190/**
191 * ibus_serializable_new:
192 *
193 * Creates a new instance of an #IBusSerializable.
194 *
195 * Returns: a new instance of #IBusSerializable.
196 */
197IBusSerializable *ibus_serializable_new (void);
198
199/**
200 * ibus_serializable_set_qattachment:
201 * @serializable: An #IBusSerializable.
202 * @key: String formatted key for indexing value.
203 * @value: Value to be attached or %NULL to remove any prevoius value.
204 *
205 * Attach a value to an #IBusSerializable. If the value is floating,
206 * the serializable will take the ownership.
207 *
208 * See also: ibus_serializable_set_attachment().
209 */
210void ibus_serializable_set_qattachment (IBusSerializable *serializable,
211 GQuark key,
212 GVariant *value);
213
214/**
215 * ibus_serializable_get_qattachment:
216 * @serializable: An #IBusSerializable.
217 * @key: String formatted key for indexing value.
218 *
219 * Gets a value from attachment of an #IBusSerializable.
220 *
221 * Returns: The attached value; or %NULL if fail to retrieve the value.
222 *
223 * See also: ibus_serializable_set_attachment().
224 */
225GVariant *ibus_serializable_get_qattachment (IBusSerializable *serializable,
226 GQuark key);
227
228/**
229 * ibus_serializable_remove_qattachment:
230 * @serializable: An #IBusSerializable.
231 * @key: String formatted key for indexing value.
232 *
233 * Remove a value from attachment of an #IBusSerializable.
234 * See also: ibus_serializable_remove_attachment().
235 */
236void ibus_serializable_remove_qattachment
237 (IBusSerializable *serializable,
238 GQuark key);
239
240/**
241 * ibus_serializable_copy:
242 * @serializable: An #IBusSerializable.
243 *
244 * Clone an #IBusSerializable.
245 * The copy method should be implemented in extended class.
246 *
247 * Returns: (transfer none): A newly allocated clone object; or %NULL
248 * if @object is not serializable.
249 *
250 * See also: IBusSerializableCopyFunc().
251 */
252IBusSerializable *ibus_serializable_copy (IBusSerializable *serializable);
253
254/**
255 * ibus_serializable_serialize_object:
256 * @serializable: An #IBusSerializable.
257 *
258 * Serialize an #IBusSerializable to a #GVariant.
259 * The serialize method should be implemented in extended class.
260 *
261 * Returns: A #GVariant.
262 *
263 * See also: IBusSerializableCopyFunc().
264 */
265GVariant *ibus_serializable_serialize_object
266 (IBusSerializable *serializable);
267
268/**
269 * ibus_serializable_deserialize_object:
270 * @variant: A #GVariant.
271 *
272 * Deserialize a #GVariant to an #IBusSerializable/
273 * The deserialize method should be implemented in extended class.
274 *
275 * Returns: (transfer none): The deserialized #IBusSerializable.
276 *
277 * See also: IBusSerializableCopyFunc().
278 */
279IBusSerializable *ibus_serializable_deserialize_object
280 (GVariant *variant);
281
282#define ibus_serializable_serialize ibus_serializable_serialize_object
283#define ibus_serializable_deserialize ibus_serializable_deserialize_object
284
285G_END_DECLS
286#endif
287
288