CamelObject

## CamelObject CamelObject |

## Synopsis

                        CamelObject;
    #define             CAMEL_ERROR
    enum                CamelError;
    enum                CamelParamFlags;
    gint                camel_object_state_read             (CamelObject *object);
    gint                camel_object_state_write            (CamelObject *object);
    const gchar *       camel_object_get_state_filename     (CamelObject *object);
    void                camel_object_set_state_filename     (CamelObject *object,
                                                             const gchar *state_filename);
                        CamelObjectBag;
    gpointer            (*CamelCopyFunc)                    (gconstpointer object);
    CamelObjectBag *    camel_object_bag_new                (GHashFunc key_hash_func,
                                                             GEqualFunc key_equal_func,
                                                             CamelCopyFunc key_copy_func,
                                                             GFreeFunc key_free_func);
    gpointer            camel_object_bag_get                (CamelObjectBag *bag,
                                                             gconstpointer key);
    gpointer            camel_object_bag_peek               (CamelObjectBag *bag,
                                                             gconstpointer key);
    gpointer            camel_object_bag_reserve            (CamelObjectBag *bag,
                                                             gconstpointer key);
    void                camel_object_bag_add                (CamelObjectBag *bag,
                                                             gconstpointer key,
                                                             gpointer object);
    void                camel_object_bag_abort              (CamelObjectBag *bag,
                                                             gconstpointer key);
    void                camel_object_bag_rekey              (CamelObjectBag *bag,
                                                             gpointer object,
                                                             gconstpointer new_key);
    GPtrArray *         camel_object_bag_list               (CamelObjectBag *bag);
    void                camel_object_bag_remove             (CamelObjectBag *bag,
                                                             gpointer object);
    void                camel_object_bag_destroy            (CamelObjectBag *bag);

## Object Hierarchy

      GObject
       +----CamelObject
             +----CamelAddress
             +----CamelBlockFile
             +----CamelKeyFile
             +----CamelCertDB
             +----CamelCipherContext
             +----CamelDataCache
             +----CamelDataWrapper
             +----CamelDiscoDiary
             +----CamelFolder
             +----CamelService
             +----CamelFilterDriver
             +----CamelFolderSearch
             +----CamelFolderSummary
             +----CamelHTMLParser
             +----CamelStream
             +----CamelIndexCursor
             +----CamelIndexName
             +----CamelIndex
             +----CamelMimeFilter
             +----CamelMimeParser
             +----CamelOfflineJournal
             +----CamelPartitionTable
             +----CamelKeyTable
             +----CamelSasl
             +----CamelSession
             +----CamelStoreSummary

## Properties

      "state-filename"           gchar*                : Read / Write / Construct

## Description

## Details

### CamelObject

    typedef struct _CamelObject CamelObject;

### CAMEL_ERROR

    #define             CAMEL_ERROR

Since 2.32

### enum CamelError

    typedef enum {
    	CAMEL_ERROR_GENERIC		/* lazy fallback error */
    } CamelError;

Since 2.32

### enum CamelParamFlags

    typedef enum {
    	CAMEL_PARAM_PERSISTENT = 1 << (G_PARAM_USER_SHIFT + 0)
    } CamelParamFlags;

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

`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

### camel_object_state_read ()

    gint                camel_object_state_read             (CamelObject *object);

Read persistent object state from "state-filename".

`object` : | a CamelObject
Returns : | -1 on error.

### camel_object_state_write ()

    gint                camel_object_state_write            (CamelObject *object);

Write persistent object state "state-filename".

`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.

`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.

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

Since 2.32

### CamelObjectBag

    typedef struct _CamelObjectBag CamelObjectBag;

### CamelCopyFunc ()

    gpointer            (*CamelCopyFunc)                    (gconstpointer object);

`object` : |
Returns : |

### 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.

`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.

`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.

`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()`.

`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()`.

`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.

`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.

`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);

`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`.

`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.

`bag` : | a CamelObjectBag

## Property Details

### The `"state-filename"` property

      "state-filename"           gchar*                : Read / Write / Construct

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

Default value: NULL