CamelObject

CamelObject

Synopsis

struct              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

Description

Details

struct CamelObject

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


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:

    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