/* -*- mode: C; c-basic-offset: 4; indent-tabs-mode: nil; -*- */
/* vim:set et sts=4: */
/* ibus - The Input Bus
* Copyright (C) 2008-2013 Peng Huang <shawn.p.huang@gmail.com>
* Copyright (C) 2018 Takao Fujiwara <takao.fujiwara1@gmail.com>
* Copyright (C) 2008-2018 Red Hat, Inc.
*
* 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
* version 2.1 of the License, or (at your option) any later version.
*
* 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.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301
* USA
*/
#if !defined (__IBUS_H_INSIDE__) && !defined (IBUS_COMPILATION)
#error "Only <ibus.h> can be included directly"
#endif
#ifndef __IBUS_SERIALIZABLE_H_
#define __IBUS_SERIALIZABLE_H_
/**
* SECTION: ibusserializable
* @short_description: A serializable object.
* @stability: Stable
*
* An #IBusSerializable is an IBus object which can be serialized, that is,
* to be to and from a #GVariant.
*
* This class is to be extended by other class that requires serialization.
* An extended class should overrides following methods:
* <itemizedlist>
* <listitem>
* <para><function>serialize(object,iter)</function>: for serialize.</para>
* </listitem>
* <listitem>
* <para><function>deserialize(object,iter)</function>: for deserialize.</para>
* </listitem>
* <listitem>
* <para><function>copy(desc,src)</function>: for copy between IBusSerializable.</para>
* </listitem>
* </itemizedlist>
* See IBusSerializableSerializeFunc(), IBusSerializableDeserializeFunc(), IBusSerializableCopyFunc()
* for function prototype.
*/
#include "ibusobject.h"
/*
* Type macros.
*/
/* define IBusSerializable macros */
#define IBUS_TYPE_SERIALIZABLE \
(ibus_serializable_get_type ())
#define IBUS_SERIALIZABLE(obj) \
(G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_SERIALIZABLE, IBusSerializable))
#define IBUS_SERIALIZABLE_CLASS(klass) \
(G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_SERIALIZABLE, IBusSerializableClass))
#define IBUS_IS_SERIALIZABLE(obj) \
(G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_SERIALIZABLE))
#define IBUS_IS_SERIALIZABLE_CLASS(klass) \
(G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_SERIALIZABLE))
#define IBUS_SERIALIZABLE_GET_CLASS(obj) \
(G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_SERIALIZABLE, IBusSerializableClass))
/**
* ibus_serializable_set_attachment:
* @o: An IBusSerializable.
* @k: String formatted key for indexing value.
* @v: Value to be attached. Should be also serializable.
*
* Attach a value to an IBusSerializable.
* This macro is an convenient wrapper of ibus_serializable_set_qattachment().
*/
#define ibus_serializable_set_attachment(o, k, v) \
ibus_serializable_set_qattachment (o, g_quark_from_string (k), v)
/**
* ibus_serializable_get_attachment:
* @o: An #IBusSerializable.
* @k: String formatted key for indexing value.
*
* Get a value from attachment of an #IBusSerializable.
* This macro is an convenient wrapper of ibus_serializable_get_qattachment().
*/
#define ibus_serializable_get_attachment(o, k) \
ibus_serializable_get_qattachment (o, g_quark_from_string (k))
/**
* ibus_serializable_remove_attachment:
* @o: An #IBusSerializable.
* @k: String formatted key for indexing value.
*
* Remove a value from attachment of an #IBusSerializable.
* This macro is an convenient wrapper of ibus_serializable_remove_qattachment().
*/
#define ibus_serializable_remove_attachment(o, k) \
ibus_serializable_remove_qattachment (o, g_quark_from_string (k))
G_BEGIN_DECLS
typedef struct _IBusSerializable IBusSerializable;
typedef struct _IBusSerializableClass IBusSerializableClass;
typedef struct _IBusSerializablePrivate IBusSerializablePrivate;
/**
* IBusSerializable:
*
* All the fields in the <structname>IBusSerializable</structname> structure are
* private to the #IBusSerializable and should never be accessed directly.
*/
struct _IBusSerializable {
/*< private >*/
IBusObject parent;
IBusSerializablePrivate *priv;
/* instance members */
};
/**
* IBusSerializableSerializeFunc:
* @serializable: An #IBusSerializable.
* @builder: A #GVariantBuilder.
*
* Prototype of serialize function.
* Serialize function convert an #IBusSerializable to #GVariantBuilder.
* Returns a gboolean value which indicates whether the conversion is success.
* Return %TRUE if succeed.
*
* Returns: %TRUE if succeed; %FALSE otherwise.
*/
typedef gboolean (* IBusSerializableSerializeFunc) (IBusSerializable *serializable,
GVariantBuilder *builder);
/**
* IBusSerializableDeserializeFunc:
* @serializable: An #IBusSerializable.
* @variant: A #GVariant contains a tuple.
*
* Prototype of deserialize function.
* Deserialize function convert a #GVariant to #IBusSerializable.
* Returns an integer value which indicates how many values in
* the variant(tuple) are consumed.
*
* Returns: The number of values in the variant(tuple) are consumed.
*/
typedef gint (* IBusSerializableDeserializeFunc) (IBusSerializable *serializable,
GVariant *variant);
/**
* IBusSerializableCopyFunc:
* @dest: The destination #IBusSerializable.
* @src: A source #IBusSerializable.
*
* Prototype of copy function.
* Copy function copy from source #IBusSerializable to the destination one.
* Returns a gboolean value which indicates whether the copying is success.
*
* Returns: %TRUE if succeed; %FALSE otherwise.
*/
typedef gboolean (* IBusSerializableCopyFunc) (IBusSerializable *dest,
const IBusSerializable *src);
struct _IBusSerializableClass {
/*< private >*/
IBusObjectClass parent;
/* virtual table */
gboolean (* serialize) (IBusSerializable *object,
GVariantBuilder *builder);
gint (* deserialize) (IBusSerializable *object,
GVariant *variant);
gboolean (* copy) (IBusSerializable *dest,
const IBusSerializable *src);
/*< private >*/
/* padding */
gpointer pdummy[5];
};
GType ibus_serializable_get_type (void);
/**
* ibus_serializable_new:
*
* Creates a new instance of an #IBusSerializable.
*
* Returns: a new instance of #IBusSerializable.
*/
IBusSerializable *ibus_serializable_new (void);
/**
* ibus_serializable_set_qattachment:
* @serializable: An #IBusSerializable.
* @key: String formatted key for indexing value.
* @value: Value to be attached or %NULL to remove any prevoius value.
*
* Attach a value to an #IBusSerializable. If the value is floating,
* the serializable will take the ownership.
*
* See also: ibus_serializable_set_attachment().
*/
void ibus_serializable_set_qattachment (IBusSerializable *serializable,
GQuark key,
GVariant *value);
/**
* ibus_serializable_get_qattachment:
* @serializable: An #IBusSerializable.
* @key: String formatted key for indexing value.
*
* Gets a value from attachment of an #IBusSerializable.
*
* Returns: The attached value; or %NULL if fail to retrieve the value.
*
* See also: ibus_serializable_set_attachment().
*/
GVariant *ibus_serializable_get_qattachment (IBusSerializable *serializable,
GQuark key);
/**
* ibus_serializable_remove_qattachment:
* @serializable: An #IBusSerializable.
* @key: String formatted key for indexing value.
*
* Remove a value from attachment of an #IBusSerializable.
* See also: ibus_serializable_remove_attachment().
*/
void ibus_serializable_remove_qattachment
(IBusSerializable *serializable,
GQuark key);
/**
* ibus_serializable_copy:
* @serializable: An #IBusSerializable.
*
* Clone an #IBusSerializable.
* The copy method should be implemented in extended class.
*
* Returns: (transfer none): A newly allocated clone object; or %NULL
* if @object is not serializable.
*
* See also: IBusSerializableCopyFunc().
*/
IBusSerializable *ibus_serializable_copy (IBusSerializable *serializable);
/**
* ibus_serializable_serialize_object:
* @serializable: An #IBusSerializable.
*
* Serialize an #IBusSerializable to a #GVariant.
* The serialize method should be implemented in extended class.
*
* Returns: A #GVariant.
*
* See also: IBusSerializableCopyFunc().
*/
GVariant *ibus_serializable_serialize_object
(IBusSerializable *serializable);
/**
* ibus_serializable_deserialize_object:
* @variant: A #GVariant.
*
* Deserialize a #GVariant to an #IBusSerializable/
* The deserialize method should be implemented in extended class.
*
* Returns: (transfer none): The deserialized #IBusSerializable.
*
* See also: IBusSerializableCopyFunc().
*/
IBusSerializable *ibus_serializable_deserialize_object
(GVariant *variant);
#define ibus_serializable_serialize ibus_serializable_serialize_object
#define ibus_serializable_deserialize ibus_serializable_deserialize_object
G_END_DECLS
#endif