Top | ![]() |
![]() |
![]() |
![]() |
EBookCacheEBookCache — An ECache descendant for addressbooks |
EBookCacheSearchData | |
struct | EBookCache |
struct | EBookCacheClass |
enum | EBookCacheCursorOrigin |
enum | EBookCacheCursorStepFlags |
EBookCacheCursor |
The EBookCache is an API for storing and looking up EContact(s) in an ECache. It also supports cursors.
The API is thread safe, in the similar way as the ECache is.
Any operations which can take a lot of time to complete (depending on the size of your addressbook) can be cancelled using a GCancellable.
Depending on your summary configuration, your mileage will vary. Refer to the ESourceBackendSummarySetup for configuring your addressbook for the type of usage you mean to make of it.
EBookCacheSearchData * e_book_cache_search_data_new (const gchar *uid
,const gchar *vcard
,const gchar *extra
);
Creates a new EBookCacheSearchData prefilled with the given values.
uid |
a contact UID; cannot be |
|
vcard |
the contact as a vCard string; cannot be |
|
extra |
any extra data stored with the contact, or |
[nullable] |
A new EBookCacheSearchData. Free it with
e_book_cache_search_data_free()
when no longer needed.
[transfer full]
Since: 3.26
EBookCacheSearchData *
e_book_cache_search_data_copy (const EBookCacheSearchData *data
);
Copy of the given data
. Free it with
e_book_cache_search_data_free()
when no longer needed.
If the data
is NULL
, then returns NULL
as well.
[transfer full]
Since: 3.26
void
e_book_cache_search_data_free (gpointer data
);
Frees the data
structure, previously allocated with e_book_cache_search_data_new()
or e_book_cache_search_data_copy()
.
Since: 3.26
gboolean (*EBookCacheSearchFunc) (EBookCache *book_cache
,const gchar *uid
,const gchar *revision
,const gchar *object
,const gchar *extra
,EOfflineState offline_state
,gpointer user_data
);
A callback called for each object row when using
e_book_cache_search_with_callback()
function.
book_cache |
an EBookCache |
|
uid |
a unique object identifier |
|
revision |
the object revision |
|
object |
the object itself |
|
extra |
extra data stored with the object |
|
offline_state |
objects offline state, one of EOfflineState |
|
user_data |
user data, as used in |
Since: 3.26
EBookCache * e_book_cache_new (const gchar *filename
,ESource *source
,GCancellable *cancellable
,GError **error
);
Creates a new EBookCache with the default summary configuration.
Aside from the mandatory fields E_CONTACT_UID
, E_CONTACT_REV
,
the default configuration stores the following fields for quick
performance of searches: E_CONTACT_FILE_AS
, E_CONTACT_NICKNAME
,
E_CONTACT_FULL_NAME
, E_CONTACT_GIVEN_NAME
, E_CONTACT_FAMILY_NAME
,
E_CONTACT_EMAIL
, E_CONTACT_TEL
, E_CONTACT_IS_LIST
, E_CONTACT_LIST_SHOW_ADDRESSES
,
and E_CONTACT_WANTS_HTML
.
The fields E_CONTACT_FULL_NAME
and E_CONTACT_EMAIL
are configured
to respond extra quickly with the E_BOOK_INDEX_PREFIX
index flag.
The fields E_CONTACT_FILE_AS
, E_CONTACT_FAMILY_NAME
and
E_CONTACT_GIVEN_NAME
are configured to perform well with
the EBookCacheCursor, using the E_BOOK_INDEX_SORT_KEY
index flag.
filename |
file name to load or create the new cache |
|
source |
an optional ESource, associated with the EBookCache, or |
[nullable] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
EBookCache * e_book_cache_new_full (const gchar *filename
,ESource *source
,ESourceBackendSummarySetup *setup
,GCancellable *cancellable
,GError **error
);
Creates a new EBookCache with the given or the default summary configuration.
Like e_book_sqlite_new()
, but allows configuration of which contact fields
will be stored for quick reference in the summary. The configuration indicated by
setup
will only be taken into account when initially creating the underlying table,
further configurations will be ignored.
The fields E_CONTACT_UID
and E_CONTACT_REV
are not optional,
they will be stored in the summary regardless of this function's parameters.
Only EContactFields with the type G_TYPE_STRING
, G_TYPE_BOOLEAN
or
E_TYPE_CONTACT_ATTR_LIST
are currently supported.
filename |
file name to load or create the new cache |
|
source |
an optional ESource, associated with the EBookCache, or |
[nullable] |
setup |
an ESourceBackendSummarySetup describing how the summary should be setup, or |
[nullable] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
ESource *
e_book_cache_ref_source (EBookCache *book_cache
);
References the ESource to which book_cache
is paired,
use g_object_unref()
when no longer needed.
It can be NULL
in some cases, like when running tests.
Since: 3.26
gchar * e_book_cache_dup_contact_revision (EBookCache *book_cache
,EContact *contact
);
Returns the contact
revision, used to detect changes.
The returned string should be freed with g_free()
, when
no longer needed.
Since: 3.26
gboolean e_book_cache_set_locale (EBookCache *book_cache
,const gchar *lc_collate
,GCancellable *cancellable
,GError **error
);
Relocalizes any locale specific data in the specified
new lc_collate
locale.
The lc_collate
locale setting is stored and remembered on
subsequent accesses of the cache, changing the locale will
store the new locale and will modify sort keys and any
locale specific data in the cache.
As a side effect, it's possible that changing the locale will cause stored vCard-s to change.
book_cache |
An EBookCache |
|
lc_collate |
The new locale for the cache |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gchar *
e_book_cache_dup_locale (EBookCache *book_cache
);
A new string containing the current local
being used by the book_cache
. Free it with g_free()
, when no
longer needed.
[transfer full]
Since: 3.26
ECollator *
e_book_cache_ref_collator (EBookCache *book_cache
);
References the currently active ECollator for book_cache
,
use e_collator_unref()
when finished using the returned collator.
Note that the active collator will change with the active locale setting.
Since: 3.26
gboolean e_book_cache_put_contact (EBookCache *book_cache
,EContact *contact
,const gchar *extra
,ECacheOfflineFlag offline_flag
,GCancellable *cancellable
,GError **error
);
This is a convenience wrapper for e_book_cache_put_contacts()
,
which is the preferred way to add or modify multiple contacts when possible.
book_cache |
An EBookCache |
|
contact |
an EContact to be added |
|
extra |
extra data to store in association with this contact |
|
offline_flag |
one of ECacheOfflineFlag, whether putting this contact in offline |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_book_cache_put_contacts (EBookCache *book_cache
,const GSList *contacts
,const GSList *extras
,ECacheOfflineFlag offline_flag
,GCancellable *cancellable
,GError **error
);
Adds or replaces contacts in book_cache
.
If extras
is specified, it must have an equal length as the contacts
list. Each element
from the extras
list will be stored in association with its corresponding contact
in the contacts
list.
book_cache |
An EBookCache |
|
contacts |
A list of contacts to add to |
[element-type EContact] |
extras |
A list of extra data to store in association with the |
[nullable][element-type utf8] |
offline_flag |
one of ECacheOfflineFlag, whether putting these contacts in offline |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_book_cache_remove_contact (EBookCache *book_cache
,const gchar *uid
,ECacheOfflineFlag offline_flag
,GCancellable *cancellable
,GError **error
);
Removes the contact identified by uid
from book_cache
.
book_cache |
An EBookCache |
|
uid |
the uid of the contact to remove |
|
offline_flag |
one of ECacheOfflineFlag, whether removing this contact in offline |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_book_cache_remove_contacts (EBookCache *book_cache
,const GSList *uids
,ECacheOfflineFlag offline_flag
,GCancellable *cancellable
,GError **error
);
Removes the contacts indicated by uids
from book_cache
.
book_cache |
An EBookCache |
|
uids |
a GSList of uids indicating which contacts to remove. |
[element-type utf8] |
offline_flag |
one of ECacheOfflineFlag, whether removing these contacts in offline |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_book_cache_get_contact (EBookCache *book_cache
,const gchar *uid
,gboolean meta_contact
,EContact **out_contact
,GCancellable *cancellable
,GError **error
);
Fetch the EContact specified by uid
in book_cache
.
If meta_contact
is specified, then a shallow EContact will be created
holding only the E_CONTACT_UID
and E_CONTACT_REV
fields.
book_cache |
An EBookCache |
|
uid |
The uid of the contact to fetch |
|
meta_contact |
Whether an entire contact is desired, or only the metadata |
|
out_contact |
Return location to store the fetched contact. |
[out][transfer full] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_book_cache_get_vcard (EBookCache *book_cache
,const gchar *uid
,gboolean meta_contact
,gchar **out_vcard
,GCancellable *cancellable
,GError **error
);
Fetch a vCard string for uid
in book_cache
.
If meta_contact
is specified, then a shallow vCard representation will be
created holding only the E_CONTACT_UID
and E_CONTACT_REV
fields.
book_cache |
An EBookCache |
|
uid |
The uid of the contact to fetch |
|
meta_contact |
Whether an entire contact is desired, or only the metadata |
|
out_vcard |
Return location to store the fetched vCard string. |
[out][transfer full] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_book_cache_set_contact_extra (EBookCache *book_cache
,const gchar *uid
,const gchar *extra
,GCancellable *cancellable
,GError **error
);
Sets or replaces the extra data associated with uid
.
book_cache |
An EBookCache |
|
uid |
The uid of the contact to set the extra data for |
|
extra |
The extra data to set. |
[nullable] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_book_cache_get_contact_extra (EBookCache *book_cache
,const gchar *uid
,gchar **out_extra
,GCancellable *cancellable
,GError **error
);
Fetches the extra data previously set for uid
, either with
e_book_cache_set_contact_extra()
or when adding contacts.
book_cache |
An EBookCache |
|
uid |
The uid of the contact to fetch the extra data for |
|
out_extra |
Return location to store the extra data. |
[out][transfer full] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_book_cache_get_uids_with_extra (EBookCache *book_cache
,const gchar *extra
,GSList **out_uids
,GCancellable *cancellable
,GError **error
);
Gets all the UID-s the extra
data is set for.
The out_uids
should be freed with
g_slist_free_full (uids, g_free);
when no longer needed.
book_cache |
an EBookCache |
|
extra |
an extra column value to search for |
|
out_uids |
return location to store the UIDs to. |
[out][transfer full][element-type utf8] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_book_cache_search (EBookCache *book_cache
,const gchar *sexp
,gboolean meta_contacts
,GSList **out_list
,GCancellable *cancellable
,GError **error
);
Searches book_cache
for contacts matching the search expression sexp
.
When sexp
refers only to EContactFields configured in the summary of book_cache
,
the search should always be quick, when searching for other EContactFields
a fallback will be used.
The returned out_list
list should be freed with g_slist_free_full (list, e_book_cache_search_data_free)
when no longer needed.
If meta_contact
is specified, then shallow vCard representations will be
created holding only the E_CONTACT_UID
and E_CONTACT_REV
fields.
book_cache |
An EBookCache |
|
sexp |
search expression; use |
[nullable] |
meta_contacts |
Whether entire contacts are desired, or only the metadata |
|
out_list |
Return location to store a GSList of EBookCacheSearchData structures. |
[out][transfer full][element-type EBookCacheSearchData] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_book_cache_search_uids (EBookCache *book_cache
,const gchar *sexp
,GSList **out_list
,GCancellable *cancellable
,GError **error
);
Similar to e_book_cache_search()
, but fetches only a list of contact UIDs.
The returned out_list
list should be freed with g_slist_free_full(list, g_free)
when no longer needed.
book_cache |
An EBookCache |
|
sexp |
search expression; use |
[nullable] |
out_list |
Return location to store a GSList of contact uids. |
[out][transfer full][element-type utf8] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_book_cache_search_with_callback (EBookCache *book_cache
,const gchar *sexp
,EBookCacheSearchFunc func
,gpointer user_data
,GCancellable *cancellable
,GError **error
);
Similar to e_book_cache_search()
, but calls the func
for each found contact.
book_cache |
An EBookCache |
|
sexp |
search expression; use |
[nullable] |
func |
an EBookCacheSearchFunc callback to call for each found row |
|
user_data |
user data for |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
EBookCacheCursor * e_book_cache_cursor_new (EBookCache *book_cache
,const gchar *sexp
,const EContactField *sort_fields
,const EBookCursorSortType *sort_types
,guint n_sort_fields
,GError **error
);
Creates a new EBookCacheCursor.
The cursor should be freed with e_book_cache_cursor_free()
when
no longer needed.
book_cache |
An EBookCache |
|
sexp |
search expression; use |
|
sort_fields |
An array of EContactField(s) as sort keys in order of priority. |
[array length=n_sort_fields] |
sort_types |
An array of EBookCursorSortTypes, one for each field in |
[array length=n_sort_fields] |
n_sort_fields |
The number of fields to sort results by |
|
error |
return location for a GError, or |
Since: 3.26
void e_book_cache_cursor_free (EBookCache *book_cache
,EBookCacheCursor *cursor
);
Frees the cursor
, previously allocated with e_book_cache_cursor_new()
.
Since: 3.26
gint e_book_cache_cursor_step (EBookCache *book_cache
,EBookCacheCursor *cursor
,EBookCacheCursorStepFlags flags
,EBookCacheCursorOrigin origin
,gint count
,GSList **out_results
,GCancellable *cancellable
,GError **error
);
Steps cursor
through its sorted query by a maximum of count
contacts
starting from origin
.
If count
is negative, then the cursor will move through the list in reverse.
If cursor
reaches the beginning or end of the query results, then the
returned list might not contain the amount of desired contacts, or might
return no results if the cursor currently points to the last contact.
Reaching the end of the list is not considered an error condition. Attempts
to step beyond the end of the list after having reached the end of the list
will however trigger an E_CACHE_ERROR_END_OF_LIST
error.
If E_BOOK_CACHE_CURSOR_STEP_FETCH
is specified in flags
, a pointer to
a NULL
GSList pointer should be provided for the out_results
parameter.
The result list will be stored to out_results
and should be freed
with g_slist_free_full (results, e_book_cache_search_data_free);
when no longer needed.
book_cache |
An EBookCache |
|
cursor |
The EBookCacheCursor to use |
|
flags |
The EBookCacheCursorStepFlags for this step |
|
origin |
The EBookCacheCursorOrigin from whence to step |
|
count |
A positive or negative amount of contacts to try and fetch |
|
out_results |
A return location to store the results, or |
[out][nullable][element-type EBookCacheSearchData][transfer full] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
The number of contacts traversed if successful, otherwise -1 is
returned and the error
is set.
Since: 3.26
void e_book_cache_cursor_set_target_alphabetic_index (EBookCache *book_cache
,EBookCacheCursor *cursor
,gint idx
);
Sets the cursor
position to an
into the alphabet active in book_cache
's locale.
After setting the target to an alphabetic index, for example the
index for letter 'E', then further calls to e_book_cache_cursor_step()
will return results starting with the letter 'E' (or results starting
with the last result in 'D', if moving in a negative direction).
The passed index must be a valid index in the active locale, knowledge on the currently active alphabet index must be obtained using ECollator APIs.
Use e_book_cache_ref_collator()
to obtain the active collator for book_cache
.
Since: 3.26
gboolean e_book_cache_cursor_set_sexp (EBookCache *book_cache
,EBookCacheCursor *cursor
,const gchar *sexp
,GError **error
);
Modifies the current query expression for cursor
. This will not
modify cursor
's state, but will change the outcome of any further
calls to e_book_cache_cursor_step()
or e_book_cache_cursor_calculate()
.
book_cache |
An EBookCache |
|
cursor |
The EBookCacheCursor to modify |
|
sexp |
The new query expression for |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_book_cache_cursor_calculate (EBookCache *book_cache
,EBookCacheCursor *cursor
,gint *out_total
,gint *out_position
,GCancellable *cancellable
,GError **error
);
Calculates the out_total
amount of results for the cursor
's query expression,
as well as the current out_position
of cursor
in the results. The out_position
is
represented as the amount of results which lead up to the current value
of cursor
, if cursor
currently points to an exact contact, the position
also includes the cursor contact.
book_cache |
An EBookCache |
|
cursor |
The EBookCacheCursor |
|
out_total |
A return location to store the total result set for this cursor. |
[out][nullable] |
out_position |
A return location to store the cursor position. |
[out][nullable] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gint e_book_cache_cursor_compare_contact (EBookCache *book_cache
,EBookCacheCursor *cursor
,EContact *contact
,gboolean *out_matches_sexp
);
Compares contact
with cursor
and returns whether contact
is less than, equal to, or greater
than cursor
.
book_cache |
An EBookCache |
|
cursor |
The EBookCacheCursor |
|
contact |
The EContact to compare |
|
out_matches_sexp |
Whether the contact matches the cursor's search expression. |
[out][nullable] |
A value that is less than, equal to, or greater than zero if contact
is found,
respectively, to be less than, to match, or be greater than the current value of cursor
.
Since: 3.26
typedef struct { gchar *uid; gchar *vcard; gchar *extra; } EBookCacheSearchData;
This structure is used to represent contacts returned
by the EBookCache from various functions
such as e_book_cache_search()
.
The extra
parameter will contain any data which was
previously passed for this contact in e_book_cache_put_contact()
or set with e_book_cache_set_contact_extra()
.
These should be freed with e_book_cache_search_data_free()
.
The |
||
The vcard string |
||
Any extra data associated with the vcard |
Since: 3.26
struct EBookCache { };
Contains only private data that should be read and manipulated using the functions below.
Since: 3.26
struct EBookCacheClass { };
Class structure for the EBookCache class.
Since: 3.26
Specifies the start position to in the list of traversed contacts
in calls to e_book_cache_cursor_step()
.
When an EBookCacheCursor is created, the current position implied by E_BOOK_CACHE_CURSOR_ORIGIN_CURRENT
is the same as E_BOOK_CACHE_CURSOR_ORIGIN_BEGIN
.
Since: 3.26
Defines the behaviour of e_book_cache_cursor_step()
.
Since: 3.26
typedef struct _EBookCacheCursor EBookCacheCursor;
An opaque cursor pointer
Since: 3.26