CamelObject

CamelObject

Functions

Properties

gchar * state-filename Read / Write / Construct

Types and Values

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