![]() |
![]() |
![]() |
evolution-kolab_libekolab Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy |
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
);
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.
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.
KOLAB_FOLDER_CONTEXT_CALENDAR
|
the ECalComponent to create the handle from |
|
the timezone information to attach to the calendar component (or NULL) |
Returns : |
a KolabMailHandle instance |
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.
KOLAB_FOLDER_CONTEXT_CONTACT
|
the EContact to create the handle from |
Returns : |
a KolabMailHandle instance |
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.
KOLAB_FOLDER_CONTEXT_CALENDAR
|
a KolabMailHandle instance |
Returns : |
a ref'd ECalComponent instance, or NULL |
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
|
a KolabMailHandle instance |
Returns : |
the timezone ECalComponent, or NULL |
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.
KOLAB_FOLDER_CONTEXT_CONTACT
|
a KolabMailHandle instance |
Returns : |
a new EContact instance, or NULL |
gboolean kolab_mail_handle_is_complete (const KolabMailHandle *self
);
Checks whether or not a KolabMailHandle instance is complete.
|
a KolabMailHandle instance |
Returns : |
TRUE if self is complete,
FALSE otherwise
|
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
|
a KolabMailHandle instance |
Returns : |
the UID string for this KolabMailHandle instance |
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.
|
a KolabMailHandle instance |
Returns : |
the IMAP folder name string for this KolabMailHandle instance (may be NULL) |