KolabMailHandle

KolabMailHandle — the abstract Kolab2 PIM email representation

Stability Level

Unstable, unless otherwise indicated

Synopsis

                    KolabMailHandleClass;
                    KolabMailHandle;
KolabMailHandle*    kolab_mail_handle_new_from_ecalcomponent
                                                        (ECalComponent *ecalcomp,
                                                         ECalComponent *timezone);
KolabMailHandle*    kolab_mail_handle_new_from_econtact (EContact *econtact);
ECalComponent*      kolab_mail_handle_get_ecalcomponent (const KolabMailHandle *self);
ECalComponent*      kolab_mail_handle_get_timezone      (const KolabMailHandle *self);
EContact*           kolab_mail_handle_get_econtact      (const KolabMailHandle *self);
gboolean            kolab_mail_handle_is_complete       (const KolabMailHandle *self);
const gchar*        kolab_mail_handle_get_uid           (const KolabMailHandle *self);
const gchar*        kolab_mail_handle_get_foldername    (const KolabMailHandle *self);

Object Hierarchy

  GObject
   +----KolabMailHandle

Description

This class is an abstract representation of a Kolab PIM email. As a minimum, a KolabMailHandle object carries a Kolab UID and can thus be used to reference a certain PIM object.

KolabMailHandle objects have a notion of being "complete" or "incomplete". In the latter case, they are merely shallow objects with very little information attached to them. Before operating on a KolabMailHandle object, make sure it is complete. An incomplete object can be completed by a call to kolab_mail_access_retrieve_handle() which will fetch the actual data from any of the caches within KolabMailAccess. To delete a PIM object, it's KolabMailHandle representation does not need to be completed.

KolabMailHandle objects carry with them a folder context, which is KOLAB_FOLDER_CONTEXT_CALENDAR or KOLAB_FOLDER_CONTEXT_CONTACT (see KolabFolderContextID), respectively. The folder context is determined by how the handle was created, this is, whether it was created by kolab_mail_handle_new_from_ecalcomponent() (context is KOLAB_FOLDER_CONTEXT_CALENDAR) or kolab_mail_handle_new_from_econtact() (context is KOLAB_FOLDER_CONTEXT_CONTACT). This context must match the context KolabMailAccess was configured for, otherwise all KolabMailAccess operations with the handle will return an error.

In order to retrieve a new Evolution PIM object from a KolabMailHandle, the contexts of the respective creation and retrieval functions must also match.

Details

KolabMailHandleClass

typedef struct {
	GObjectClass parent_class;
} KolabMailHandleClass;

KolabMailHandle

typedef struct _KolabMailHandle KolabMailHandle;

kolab_mail_handle_new_from_ecalcomponent ()

KolabMailHandle*    kolab_mail_handle_new_from_ecalcomponent
                                                        (ECalComponent *ecalcomp,
                                                         ECalComponent *timezone);

Creates a new KolabMailHandle from ecalcomp. The ecalcomp data is checked and attached to the KolabMailHandle, and so is the timezone data (if supplied). The timezone may be NULL if none is to be set explicitly. The newly created handle should be handed over to KolabMailAccess as soon as possible by a call to kolab_mail_access_store_handle().

The refcount of each ECalComponent passed in gets incremented. g_object_unref() any passed-in ECalComponent if no longer needed outside the KolabMailHandle.

This sets the KOLAB_FOLDER_CONTEXT_CALENDAR context on the handle, which means that it can be passed to a KolabMailAccess only if the latter is configured with the same context.

  • Handle precondition: none
  • Handle postcondition: complete, KOLAB_FOLDER_CONTEXT_CALENDAR

ecalcomp :

the ECalComponent to create the handle from

timezone :

the timezone information to attach to the calendar component (or NULL)

Returns :

a KolabMailHandle instance

kolab_mail_handle_new_from_econtact ()

KolabMailHandle*    kolab_mail_handle_new_from_econtact (EContact *econtact);

Creates a new KolabMailHandle from econtact. The econtact data is checked and attached to the KolabMailHandle. The newly created handle should be handed over to KolabMailAccess as soon as possible by a call to kolab_mail_access_store_handle().

The refcount of the EContact passed in gets incremented. g_object_unref() the passed-in EContact if no longer needed outside the KolabMailHandle.

This sets the KOLAB_FOLDER_CONTEXT_CONTACT context on the handle, which means that it can be passed to a KolabMailAccess only if the latter is configured with the same context.

  • Handle precondition: none
  • Handle postcondition: complete, KOLAB_FOLDER_CONTEXT_CONTACT

econtact :

the EContact to create the handle from

Returns :

a KolabMailHandle instance

kolab_mail_handle_get_ecalcomponent ()

ECalComponent*      kolab_mail_handle_get_ecalcomponent (const KolabMailHandle *self);

Returns the ECalComponent instance associated with the handle with it's refcount incremented by 1. Unref the ECalComponent if it is no longer needed outside the handle. If there is timezone information attached to the ECalComponent, it can be queried for with a subsequent call to kolab_mail_handle_get_timezone(). The timezone may be NULL if none was set on the PIM data object.

This requires the KOLAB_FOLDER_CONTEXT_CALENDAR context be set on the handle. The handle must be complete in order to retrieve an ECalComponent from it. If the handle is incomplete, the function returns NULL.

  • Handle precondition: complete, KOLAB_FOLDER_CONTEXT_CALENDAR
  • Handle postcondition: none

self :

a KolabMailHandle instance

Returns :

a ref'd ECalComponent instance, or NULL

kolab_mail_handle_get_timezone ()

ECalComponent*      kolab_mail_handle_get_timezone      (const KolabMailHandle *self);

Gets the timezone information as an ECalComponent from this KolabMailHandle instance. The return value is NULL if there is no timezone information. This function is useful only in KOLAB_FOLDER_CONTEXT_CALENDAR context. The refcount on the ECalComponent returned is incremented by one, if the component is not NULL

  • Handle precondition: none
  • Handle postcondition: none

self :

a KolabMailHandle instance

Returns :

the timezone ECalComponent, or NULL

kolab_mail_handle_get_econtact ()

EContact*           kolab_mail_handle_get_econtact      (const KolabMailHandle *self);

Returns the EContact instance associated with the handle with it's refcount incremented by 1. Unref the EContact if it is no longer needed outside the handle.

This requires the KOLAB_FOLDER_CONTEXT_CONTACT context be set on the handle. The handle must be complete in order to retrieve an EContact from it. If the handle is incomplete, the function returns NULL.

  • Handle precondition: complete, KOLAB_FOLDER_CONTEXT_CONTACT
  • Handle postcondition: none

self :

a KolabMailHandle instance

Returns :

a new EContact instance, or NULL

kolab_mail_handle_is_complete ()

gboolean            kolab_mail_handle_is_complete       (const KolabMailHandle *self);

Checks whether or not a KolabMailHandle instance is complete.

  • Handle precondition: none
  • Handle postcondition: none

self :

a KolabMailHandle instance

Returns :

TRUE if self is complete, FALSE otherwise

kolab_mail_handle_get_uid ()

const gchar*        kolab_mail_handle_get_uid           (const KolabMailHandle *self);

Gets the UID string from a KolabMailHandle instance. It is an error if there is no UID associated with a KolabMailHandle instance.

TODO check whether this function should throw a critical error in case of a NULL UID instead of a warning only

  • Handle precondition: none
  • Handle postcondition: none

self :

a KolabMailHandle instance

Returns :

the UID string for this KolabMailHandle instance

kolab_mail_handle_get_foldername ()

const gchar*        kolab_mail_handle_get_foldername    (const KolabMailHandle *self);

Gets the IMAP folder name this KolabMailHandle instance is stored in. If the mail handle has not yet been stored within KolabMailAccess by a call to kolab_mail_access_store_handle(), the folder name returned is NULL.

  • Handle precondition: none
  • Handle postcondition: none

self :

a KolabMailHandle instance

Returns :

the IMAP folder name string for this KolabMailHandle instance (may be NULL)

See Also

KolabMailAccess