## KolabMailHandle KolabMailHandle — the abstract Kolab2 PIM email representation |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

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

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

### struct KolabMailHandleClass

    struct KolabMailHandleClass {
    	GObjectClass parent_class;
    };

### 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_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_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)

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

## See Also

KolabMailAccess