CamelObject: Camel Reference Manual

## CamelObject CamelObject |

## Functions

gint | camel_object_state_read ()
gint | camel_object_state_write ()
const gchar * | camel_object_get_state_filename ()
void | camel_object_set_state_filename ()
gpointer | (*CamelCopyFunc) ()
CamelObjectBag * | camel_object_bag_new ()
gpointer | camel_object_bag_get ()
gpointer | camel_object_bag_peek ()
gpointer | camel_object_bag_reserve ()
void | camel_object_bag_add ()
void | camel_object_bag_abort ()
void | camel_object_bag_rekey ()
GPtrArray * | camel_object_bag_list ()
void | camel_object_bag_remove ()
void | camel_object_bag_destroy ()

## Properties

gchar * | state-filename | Read / Write / Construct

## Types and Values

struct | CamelObject
#define | CAMEL_ERROR
enum | CamelError
enum | CamelParamFlags
| CamelObjectBag

## Object Hierarchy

        GObject
        ╰── CamelObject
            ├── CamelFolder
            ╰── CamelService

## Description

## Functions

### camel_object_state_read ()

    gint
    camel_object_state_read (CamelObject *object);

Read persistent object state from “state-filename”.

#### Parameters

object | a CamelObject |

#### Returns

-1 on error.

### camel_object_state_write ()

    gint
    camel_object_state_write (CamelObject *object);

Write persistent object state “state-filename”.

#### Parameters

object | a CamelObject |

#### Returns

-1 on error.

### camel_object_get_state_filename ()

    const gchar *
    camel_object_get_state_filename (CamelObject *object);

Returns the name of the file in which persistent property values for `object` are stored. The file is used by `camel_object_state_write()` and `camel_object_state_read()` to save and restore object state.

#### Parameters

object | a CamelObject |

#### Returns

the name of the persistent property file

Since: 2.32

### camel_object_set_state_filename ()

    void
    camel_object_set_state_filename (CamelObject *object,
                                     const gchar *state_filename);

Sets the name of the file in which persistent property values for `object` are stored. The file is used by `camel_object_state_write()` and `camel_object_state_read()` to save and restore object state.

#### Parameters

object | a CamelObject |
state_filename | path to a local file |

Since: 2.32

### CamelCopyFunc ()

    gpointer
    (*CamelCopyFunc) (gconstpointer object);

### camel_object_bag_new ()

    CamelObjectBag *
    camel_object_bag_new (GHashFunc key_hash_func,
                          GEqualFunc key_equal_func,
                          CamelCopyFunc key_copy_func,
                          GFreeFunc key_free_func);

Returns a new object bag. Object bags are keyed hash tables of objects that can be updated atomically using transaction semantics. Use `camel_object_bag_destroy()` to free the object bag.

#### Parameters

key_hash_func | a hashing function for keys |
key_equal_func | a comparison function for keys |
key_copy_func | a function to copy keys |
key_free_func | a function to free keys |

#### Returns

a newly-allocated CamelObjectBag

### camel_object_bag_get ()

    gpointer
    camel_object_bag_get (CamelObjectBag *bag,
                          gconstpointer key);

Lookup an object by `key` . If the key is currently reserved, the function will block until another thread commits or aborts the reservation. The caller owns the reference to the returned object. Use `g_object_unref()` to unreference it.

#### Parameters

bag | a CamelObjectBag |
key | a key |

#### Returns

the object corresponding to `key` , or `NULL` if not found

### camel_object_bag_peek ()

    gpointer
    camel_object_bag_peek (CamelObjectBag *bag,
                           gconstpointer key);

Returns the object for `key` in `bag` , ignoring any reservations. If it isn't committed, then it isn't considered. This should only be used where reliable transactional-based state is not required.

Unlink other "peek" operations, the caller owns the returned object reference. Use `g_object_unref()` to unreference it.

#### Parameters

bag | a CamelObjectBag |
key | an unreserved key |

#### Returns

the object for `key` , or `NULL` if `key` is reserved or not found

### camel_object_bag_reserve ()

    gpointer
    camel_object_bag_reserve (CamelObjectBag *bag,
                              gconstpointer key);

Reserves `key` in `bag` . If `key` is already reserved in another thread, then wait until the reservation has been committed.

After reserving `key` , you either get a reference to the object corresponding to `key` (similar to `camel_object_bag_get()`) or you get `NULL`, signifying that you MUST call either `camel_object_bag_add()` or `camel_object_bag_abort()`.

#### Parameters

bag | a CamelObjectBag |
key | the key to reserve |

#### Returns

the object for `key` , or `NULL` if `key` is not found

### camel_object_bag_add ()

    void
    camel_object_bag_add (CamelObjectBag *bag,
                          gconstpointer key,
                          gpointer object);

Adds `object` to `bag` . The `key` MUST have been previously reserved using `camel_object_bag_reserve()`.

#### Parameters

bag | a CamelObjectBag |
key | a reserved key |
object | a GObject |

### camel_object_bag_abort ()

    void
    camel_object_bag_abort (CamelObjectBag *bag,
                            gconstpointer key);

Aborts a key reservation.

#### Parameters

bag | a CamelObjectBag |
key | a reserved key |

### camel_object_bag_rekey ()

    void
    camel_object_bag_rekey (CamelObjectBag *bag,
                            gpointer object,
                            gconstpointer new_key);

Changes the key for `object` to `new_key` , atomically.

It is considered a programming error if `object` is not found in `bag` . In such case the function will emit a terminal warning and return.

#### Parameters

bag | a CamelObjectBag |
object | a GObject |
new_key | a new key for `object` |

### camel_object_bag_list ()

    GPtrArray *
    camel_object_bag_list (CamelObjectBag *bag);

Returns a GPtrArray of all the objects in the bag. The caller owns both the array and the object references, so to free the array use:

    1
    2
    g_ptr_array_foreach (array, g_object_unref, NULL);
    g_ptr_array_free (array, TRUE);

#### Parameters

bag | a CamelObjectBag |

#### Returns

an array of objects in `bag`

### camel_object_bag_remove ()

    void
    camel_object_bag_remove (CamelObjectBag *bag,
                             gpointer object);

Removes `object` from `bag` .

#### Parameters

bag | a CamelObjectBag |
object | a GObject |

### camel_object_bag_destroy ()

    void
    camel_object_bag_destroy (CamelObjectBag *bag);

Frees `bag` . As a precaution, the function will emit a warning to standard error and return without freeing `bag` if `bag` still has reserved keys.

#### Parameters

bag | a CamelObjectBag |

## Types and Values

### struct CamelObject

    struct CamelObject;

### CAMEL_ERROR

    #define             CAMEL_ERROR

Since: 2.32

### enum CamelError

#### Members

CAMEL_ERROR_GENERIC |  |

Since: 2.32

### enum CamelParamFlags

These flags extend GParamFlags. Most of the time you will use them in conjunction with `g_object_class_install_property()`.

#### Members

CAMEL_PARAM_PERSISTENT | The parameter is persistent, which means its value is saved to “state-filename” during `camel_object_state_write()`, and restored during `camel_object_state_read()`. |

Since: 2.32

### CamelObjectBag

    typedef struct _CamelObjectBag CamelObjectBag;

## Property Details

### The `“state-filename”` property

      “state-filename”           gchar *

The file in which to store persistent property values for this instance.

Flags: Read / Write / Construct

Default value: NULL