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