Top | ![]() |
![]() |
![]() |
![]() |
CamelStoreSearchCamelStoreSearch — search between multiple folders of one CamelStore |
The CamelStoreSearch allows to search between multiple folders of a single CamelStore. It's primarily meant to be used by the search folders (CamelVeeFolder), but it can be used without it too.
It can run only one search at a time, using camel_store_search_rebuild_sync()
.
The CamelStoreSearch is not thread safe, it's meant to be created, used and freed from within the same thread only.
guint32
camel_store_search_item_get_n_additional_values
(CamelStoreSearchItem *self
);
Gets how many additional column values had been read. These are
related to the camel_store_search_set_additional_columns()
.
Since: 3.58
const gchar * camel_store_search_item_get_additional_value (CamelStoreSearchItem *self
,guint32 index
);
Gets value of an additional column of an index index
, which
should be less than camel_store_search_item_get_n_additional_values()
.
The order corresponds to the camel_store_search_get_additional_columns()
.
Asking for an index which out of bounds returns NULL
.
Note the actual read value can be also NULL
.
Since: 3.58
CamelStore *
camel_store_search_thread_item_get_store
(const CamelStoreSearchThreadItem *self
);
Gets the CamelStore for the self
.
Since: 3.58
guint32
camel_store_search_thread_item_get_folder_id
(const CamelStoreSearchThreadItem *self
);
Gets the folder ID for the self
.
Since: 3.58
const gchar *
camel_store_search_thread_item_get_uid
(const CamelStoreSearchThreadItem *self
);
Gets the message UID for the self
.
Since: 3.58
const gchar *
camel_store_search_thread_item_get_subject
(const CamelStoreSearchThreadItem *self
);
Gets the message subject for the self
.
Since: 3.58
guint64
camel_store_search_thread_item_get_message_id
(const CamelStoreSearchThreadItem *self
);
Gets a hashed value of the Message-ID header for the self
.
Since: 3.58
const GArray *
camel_store_search_thread_item_get_references
(const CamelStoreSearchThreadItem *self
);
Gets the message In-Reply-To and References values for the self
,
hashed the same way the camel_store_search_thread_item_get_message_id()
is.
the message In-Reply-To
and References values for the self
, or NULL
, when none is set.
[nullable][transfer none][element-type guint64]
Since: 3.58
CamelStoreSearchIndex *
camel_store_search_index_new (void
);
Creates a new CamelStoreSearchIndex. Free it with camel_store_search_index_unref()
,
when no longer needed.
Since: 3.58
CamelStoreSearchIndex *
camel_store_search_index_ref (CamelStoreSearchIndex *self
);
Adds a reference on the self
. Call a pair camel_store_search_index_unref()
to remove the added reference.
Since: 3.58
void
camel_store_search_index_unref (CamelStoreSearchIndex *self
);
Removes one reference on the self
. When the reference count
drops to zero, the self
is freed.
Since: 3.58
void camel_store_search_index_add (CamelStoreSearchIndex *self
,CamelStore *store
,guint32 folder_id
,const gchar *uid
);
Adds a message identified by the store
, folder_id
and uid
into the index self
.
It can be asked whether the self
contains the message with camel_store_search_index_contains()
.
Note the store
is not referenced, it's compared pointer-wise.
See camel_store_search_index_contains()
for more information.
self |
||
store |
a CamelStore. |
[not nullable] |
folder_id |
a folder ID, other than zero |
|
uid |
a message UID. |
[not nullable] |
Since: 3.58
gboolean camel_store_search_index_remove (CamelStoreSearchIndex *self
,CamelStore *store
,guint32 folder_id
,const gchar *uid
);
Removes a message identified by the store
, folder_id
and uid
from the index self
.
Note the store
is not referenced, it's compared pointer-wise.
See camel_store_search_index_add()
for more information.
self |
||
store |
a CamelStore. |
[not nullable] |
folder_id |
a folder ID, other than zero |
|
uid |
a message UID. |
[not nullable] |
Since: 3.58
void camel_store_search_index_move_from_existing (CamelStoreSearchIndex *self
,CamelStoreSearchIndex *src
);
Moves all items from the src
index into the self
. The self
and
the src
can be the same, in which case the function does nothing.
At the end of the function the src
will contain no items, but it
is not freed.
Since: 3.58
gboolean camel_store_search_index_contains (CamelStoreSearchIndex *self
,CamelStore *store
,guint32 folder_id
,const gchar *uid
);
Checks whether a message identified by the store
, folder_id
and uid
is
included in the index self
.
Note the store
is not referenced, it's compared pointer-wise, thus when
a different instance of the same service as the one used in
the camel_store_search_index_add()
is used here, the message reference will
not be found.
self |
||
store |
a CamelStore. |
[not nullable] |
folder_id |
a folder ID, other than zero |
|
uid |
a message UID. |
[not nullable] |
Since: 3.58
void camel_store_search_index_apply_match_threads (CamelStoreSearchIndex *self
,GPtrArray *items
,CamelMatchThreadsKind kind
,CamelFolderThreadFlags flags
,GCancellable *cancellable
);
Constructs the inout_threads
from the items
according to the flags
and then
changes the content of the self
to contain only references to messages which
satisfy the kind
. When there are no items
or the kind
is CAMEL_MATCH_THREADS_KIND_NONE
,
the function does nothing.
self |
||
items |
all items used for thread creation. |
[element-type CamelStoreSearchThreadItem] |
kind |
one of CamelMatchThreadsKind |
|
flags |
a bit-or of CamelFolderThreadFlags |
|
cancellable |
a GCancellable, or NULL |
Since: 3.58
CamelStoreSearch *
camel_store_search_new (CamelStore *store
);
Creates a new CamelStoreSearch, which will operate
on folders from the store
.
Since: 3.58
CamelStore *
camel_store_search_get_store (CamelStoreSearch *self
);
Gets a CamelStore the self
was constructed for.
Since: 3.58
void camel_store_search_set_expression (CamelStoreSearch *self
,const gchar *expression
);
Sets the search expression
to be used to search the messages
in the selected folders with.
The expression can be NULL
, to not search the folders.
The content is not updated automatically, call camel_store_search_rebuild_sync()
to rebuild the content.
Since: 3.58
const gchar *
camel_store_search_get_expression (CamelStoreSearch *self
);
Gets search expression previously set by the camel_store_search_set_expression()
.
Since: 3.58
void camel_store_search_set_additional_columns (CamelStoreSearch *self
,const GPtrArray *colnames
);
Sets what additional column names should be pre-read and provided
in the camel_store_search_get_items_sync()
result. An empty array is
the same as passing NULL
for the colnames
.
Make sure to call camel_store_search_rebuild_sync()
to have the values
read.
Since: 3.58
void camel_store_search_add_folder (CamelStoreSearch *self
,CamelFolder *folder
);
Adds the folder
to the list of the folders to be searched in
by the self
. The function does nothing when the folder
is
already part of the folder
.
The content is not updated automatically, call camel_store_search_rebuild_sync()
to rebuild the content.
It's an error to try to add a folder
which is not owned by
the CamelStore the self
was created with.
Since: 3.58
void camel_store_search_remove_folder (CamelStoreSearch *self
,CamelFolder *folder
);
Removes the folder
from the list of the folders the self
should search in. It does nothing when the folder
is not part
of the self
.
The content is not updated automatically, call camel_store_search_rebuild_sync()
to rebuild the content.
Since: 3.58
GPtrArray *
camel_store_search_list_folders (CamelStoreSearch *self
);
Lists the CamelFolder-s the self
searches in.
Free the returned GPtrArray with g_ptr_array_unref()
, when
no longer needed.
a newly
created GPtrArray with the CamelFolder instances the self
searches in.
[transfer container][element-type CamelFolder]
Since: 3.58
gboolean camel_store_search_rebuild_sync (CamelStoreSearch *self
,GCancellable *cancellable
,GError **error
);
Rebuilds content of the self
with the current search expression.
The function does nothing when no search expression is set. It can
be called with no folder set, then it parses the expression and
sets the values for the camel_store_search_get_match_threads_kind()
.
Since: 3.58
gboolean camel_store_search_get_items_sync (CamelStoreSearch *self
,GPtrArray **out_items
,GCancellable *cancellable
,GError **error
);
Reads all the items from all the set folders satisfying the set expression.
Free the out_items
array with g_ptr_array_unref()
, when no longer needed.
self |
||
out_items |
an output argument for the CamelStoreSearchItem items. |
[out][transfer container][element-type CamelStoreSearchItem] |
cancellable |
a GCancellable, or NULL |
|
error |
return location for a GError, or |
Since: 3.58
gboolean camel_store_search_get_uids_sync (CamelStoreSearch *self
,const gchar *folder_name
,GPtrArray **out_uids
,GCancellable *cancellable
,GError **error
);
Reads all the message UID-s from the folder folder_name
satisfying
the set expression. Sets the out_uids
to NULL
and returns TRUE
when the folder_name
is not part of the self
.
Free the out_uids
array with g_ptr_array_unref()
, when no longer needed.
self |
||
folder_name |
name of the folder to read UID-s from |
|
out_uids |
an output argument for the read message UID-s. |
[out][transfer container][element-type utf8] |
cancellable |
a GCancellable, or NULL |
|
error |
return location for a GError, or |
Since: 3.58
CamelMatchThreadsKind camel_store_search_get_match_threads_kind (CamelStoreSearch *self
,CamelFolderThreadFlags *out_flags
);
Gets the kind of the 'match-threads' search statement of the expression
as recognized by the last camel_store_search_rebuild_sync()
call, as one
of the CamelMatchThreadsKind values.
When it's other than CAMEL_MATCH_THREADS_KIND_NONE
, the caller should gather
thread-related data with camel_store_search_add_match_threads_items_sync()
,
after which the caller filters the output to a CamelStoreSearchIndex, which
can be set back with the camel_store_search_set_result_index()
.
Since: 3.58
gboolean camel_store_search_add_match_threads_items_sync (CamelStoreSearch *self
,GPtrArray **inout_items
,GCancellable *cancellable
,GError **error
);
Adds CamelStoreSearchThreadItem items into the location pointed
to by the inout_items
array. When it points to the NULL
, the array
is created if needed. Free the array with g_ptr_array_unref()
, when
no longer needed.
See camel_store_search_get_match_threads_kind()
.
self |
||
inout_items |
a GPtrArray to add the items to. |
[inout][element-type CamelStoreSearchThreadItem][transfer container] |
cancellable |
a GCancellable, or NULL |
|
error |
return location for a GError, or |
Since: 3.58
CamelStoreSearchIndex *
camel_store_search_ref_result_index (CamelStoreSearch *self
);
Gets a CamelStoreSearchIndex being used as a search result index,
previously set by camel_store_search_set_result_index()
, or NULL
,
when none is set.
Free the returned index with camel_store_search_index_unref()
, when
no longer needed.
a referenced CamelStoreSearchIndex
used as a result index, or NULL
, when none is set.
[nullable][transfer full]
Since: 3.58
void camel_store_search_set_result_index (CamelStoreSearch *self
,CamelStoreSearchIndex *index
);
Sets, or unsets, a CamelStoreSearchIndex to be used for the search. The index contains all the items satisfying the expression.
Since: 3.58
void camel_store_search_add_match_index (CamelStoreSearch *self
,CamelStoreSearchIndex *index
);
Adds a match index index
into the self
. It can be referenced
in the search expression with 'in-match-index "index_key"'
statement, where the index_key is "p
" of the index
.
The self
adds its own reference on the index
.
Since: 3.58
void camel_store_search_remove_match_index (CamelStoreSearch *self
,CamelStoreSearchIndex *index
);
Removes the index
from from list of the match indexes. The function
does nothing when the index
is not part of the match indexes.
Since: 3.58
typedef struct { guint32 folder_id; const gchar *uid; } CamelStoreSearchItem;
A search item object, as returned by the camel_store_search_get_items_sync()
.
It can contain additional values, as requested by the camel_store_search_set_additional_columns()
,
which can be obtained by camel_store_search_item_get_n_additional_values()
and camel_store_search_item_get_additional_value()
.
Since: 3.58
typedef struct _CamelStoreSearchIndex CamelStoreSearchIndex;
A structure with search result indexes, holding references to matching records
using the CamelStore, folder ID and message UID triple. Items can be added
to the index with camel_store_search_index_add()
and checked its existence
with camel_store_search_index_contains()
.
Since: 3.58
typedef struct _CamelStoreSearchItemPrivate CamelStoreSearchItemPrivate;
typedef struct _CamelStoreSearchThreadItem CamelStoreSearchThreadItem;
A structure holding data necessary to construct message threads
using CamelFolderThread. It's gathered by camel_store_search_add_match_threads_items_sync()
.
Since: 3.58
“store”
property“store” CamelStore *
A CamelStore this search works with.
Owner: CamelStoreSearch
Flags: Read / Write / Construct Only
Since: 3.58