IBusSerializable

## IBusSerializable IBusSerializable — A serializable object. |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    struct              IBusSerializable;
    struct              IBusSerializableClass;
    gboolean            (*IBusSerializableCopyFunc)         (IBusSerializable *dest,
                                                             const IBusSerializable *src);
    gint                (*IBusSerializableDeserializeFunc)  (IBusSerializable *serializable,
                                                             GVariant *variant);
    gboolean            (*IBusSerializableSerializeFunc)    (IBusSerializable *serializable,
                                                             GVariantBuilder *builder);
    IBusSerializable *  ibus_serializable_copy              (IBusSerializable *serializable);
    IBusSerializable *  ibus_serializable_deserialize       (GVariant *variant);
    #define             ibus_serializable_get_attachment    (o,
                                                             k)
    GVariant *          ibus_serializable_get_qattachment   (IBusSerializable *serializable,
                                                             GQuark key);
    IBusSerializable *  ibus_serializable_new               (void);
    #define             ibus_serializable_remove_attachment (o,
                                                             k)
    void                ibus_serializable_remove_qattachment
                                                            (IBusSerializable *serializable,
                                                             GQuark key);
    GVariant *          ibus_serializable_serialize         (IBusSerializable *serializable);
    #define             ibus_serializable_set_attachment    (o,
                                                             k,
                                                             v)
    void                ibus_serializable_set_qattachment   (IBusSerializable *serializable,
                                                             GQuark key,
                                                             GVariant *value);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----IBusObject
                   +----IBusSerializable
                         +----IBusHotkeyProfile
                         +----IBusText
                         +----IBusAttribute
                         +----IBusAttrList
                         +----IBusEngineDesc
                         +----IBusLookupTable
                         +----IBusComponent
                         +----IBusProperty
                         +----IBusPropList
                         +----IBusObservedPath

## Description

An IBusSerializable is an IBus object which can be serialized, that is, to be to and from an IBusMessage.

This class is to be extended by other class that requires serialization. An extended class should overrides following methods:

- `serialize(object,iter)`: for serialize.

- `deserialize(object,iter)`: for deserialize.

- `copy(desc,src)`: for copy between IBusSerializable.

See `IBusSerializableSerializeFunc()`, `IBusSerializableDeserializeFunc()`, `IBusSerializableCopyFunc()` for function prototype.

## Details

### struct IBusSerializable

    struct IBusSerializable;

All the fields in the IBusSerializable structure are private to the IBusSerializable and should never be accessed directly.

### struct IBusSerializableClass

    struct IBusSerializableClass {
    };

### IBusSerializableCopyFunc ()

    gboolean            (*IBusSerializableCopyFunc)         (IBusSerializable *dest,
                                                             const IBusSerializable *src);

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.

`dest` : | The destination IBusSerializable.
`src` : | A source IBusMessageIter.
Returns : | `TRUE` if succeed; `FALSE` otherwise.

### IBusSerializableDeserializeFunc ()

    gint                (*IBusSerializableDeserializeFunc)  (IBusSerializable *serializable,
                                                             GVariant *variant);

Prototype of deserialize function. Deserialize function convert an IBusMessageIter to IBusSerializable. Returns an integer value which indicates how many values in the variant(tuple) are consumed.

`serializable` : | An IBusSerializable.
`variant` : | A GVariant contains a tuple.
Returns : | The number of values in the variant(tuple) are consumed.

### IBusSerializableSerializeFunc ()

    gboolean            (*IBusSerializableSerializeFunc)    (IBusSerializable *serializable,
                                                             GVariantBuilder *builder);

Prototype of serialize function. Serialize function convert an IBusSerializable to IBusMessageIter. Returns a gboolean value which indicates whether the conversion is success. Return `TRUE` if succeed.

`serializable` : | An IBusSerializable.
`builder` : | A GVariantBuilder.
Returns : | `TRUE` if succeed; `FALSE` otherwise.

### ibus_serializable_copy ()

    IBusSerializable *  ibus_serializable_copy              (IBusSerializable *serializable);

Clone an IBusSerializable. The copy method should be implemented in extended class.

`see_also`: `IBusSerializableCopyFunc()`.

`serializable` : | An IBusSerializable.
Returns : | A newly allocated clone object; or `NULL` if `object` is not serializable.

### ibus_serializable_deserialize ()

    IBusSerializable *  ibus_serializable_deserialize       (GVariant *variant);

Deserialize a GVariant to an IBusSerializable/ The deserialize method should be implemented in extended class.

`see_also`: `IBusSerializableCopyFunc()`.

`variant` : | A GVariant.
Returns : | The deserialized IBusSerializable.

### ibus_serializable_get_attachment()

    #define             ibus_serializable_get_attachment(o, k)

Get a value from attachment of an IBusSerializable. This macro is an convenient wrapper of `ibus_serializable_get_qattachment()`.

`o` : | An IBusSerializable.
`k` : | String formatted key for indexing value.

### ibus_serializable_get_qattachment ()

    GVariant *          ibus_serializable_get_qattachment   (IBusSerializable *serializable,
                                                             GQuark key);

Get a value from attachment of an IBusSerializable. `see_also`: `ibus_serializable_set_attachment()`.

`serializable` : | An IBusSerializable.
`key` : | String formatted key for indexing value.
Returns : | The attached value; or `NULL` if fail to retrieve the value.

### ibus_serializable_new ()

    IBusSerializable *  ibus_serializable_new               (void);

Creates a new instance of an IBusSerializable.

Returns : | a new instance of IBusSerializable.

### ibus_serializable_remove_attachment()

    #define             ibus_serializable_remove_attachment(o, k)

Remove a value from attachment of an IBusSerializable. This macro is an convenient wrapper of `ibus_serializable_remove_qattachment()`.

`o` : | An IBusSerializable.
`k` : | String formatted key for indexing value.

### ibus_serializable_remove_qattachment ()

    void                ibus_serializable_remove_qattachment
                                                            (IBusSerializable *serializable,
                                                             GQuark key);

Remove a value from attachment of an IBusSerializable. `see_also`: `ibus_serializable_remove_attachment()`.

`serializable` : | An IBusSerializable.
`key` : | String formatted key for indexing value.

### ibus_serializable_serialize ()

    GVariant *          ibus_serializable_serialize         (IBusSerializable *serializable);

Serialize an IBusSerializable to a GVariant. The serialize method should be implemented in extended class.

`see_also`: `IBusSerializableCopyFunc()`.

`serializable` : | An IBusSerializable.
Returns : | A GVariant.

### ibus_serializable_set_attachment()

    #define             ibus_serializable_set_attachment(o, k, v)

Attach a value to an IBusSerializable. This macro is an convenient wrapper of `ibus_serializable_set_qattachment()`.

`o` : | An IBusSerializable.
`k` : | String formatted key for indexing value.
`v` : | Value to be attached. Should be also serializable.

### ibus_serializable_set_qattachment ()

    void                ibus_serializable_set_qattachment   (IBusSerializable *serializable,
                                                             GQuark key,
                                                             GVariant *value);

Attach a value to an IBusSerializable. If the value is floating, the serializable will take the ownership.

`see_also`: `ibus_serializable_set_attachment()`.

`serializable` : | An IBusSerializable.
`key` : | String formatted key for indexing value.
`value` : | Value to be attached or `NULL` to remove any prevoius value.