CamelStoreSearch

CamelStoreSearch — search between multiple folders of one CamelStore

Functions

guint32 camel_store_search_item_get_n_additional_values ()
const gchar * camel_store_search_item_get_additional_value ()
CamelStore * camel_store_search_thread_item_get_store ()
guint32 camel_store_search_thread_item_get_folder_id ()
const gchar * camel_store_search_thread_item_get_uid ()
const gchar * camel_store_search_thread_item_get_subject ()
guint64 camel_store_search_thread_item_get_message_id ()
const GArray * camel_store_search_thread_item_get_references ()
CamelStoreSearchIndex * camel_store_search_index_new ()
CamelStoreSearchIndex * camel_store_search_index_ref ()
void camel_store_search_index_unref ()
void camel_store_search_index_add ()
gboolean camel_store_search_index_remove ()
void camel_store_search_index_move_from_existing ()
gboolean camel_store_search_index_contains ()
void camel_store_search_index_apply_match_threads ()
CamelStoreSearch * camel_store_search_new ()
CamelStore * camel_store_search_get_store ()
void camel_store_search_set_expression ()
const gchar * camel_store_search_get_expression ()
void camel_store_search_set_additional_columns ()
void camel_store_search_add_folder ()
void camel_store_search_remove_folder ()
GPtrArray * camel_store_search_list_folders ()
gboolean camel_store_search_rebuild_sync ()
gboolean camel_store_search_get_items_sync ()
gboolean camel_store_search_get_uids_sync ()
CamelMatchThreadsKind camel_store_search_get_match_threads_kind ()
gboolean camel_store_search_add_match_threads_items_sync ()
CamelStoreSearchIndex * camel_store_search_ref_result_index ()
void camel_store_search_set_result_index ()
void camel_store_search_add_match_index ()
void camel_store_search_remove_match_index ()

Properties

CamelStore * store Read / Write / Construct Only

Types and Values

Object Hierarchy

    GBoxed
    ╰── CamelStoreSearchIndex
    GObject
    ╰── CamelStoreSearch

Includes

#include <camel/camel.h>

Description

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.

Functions

camel_store_search_item_get_n_additional_values ()

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().

Parameters

Returns

how many additional column values had been read

Since: 3.58


camel_store_search_item_get_additional_value ()

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.

Parameters

self

a CamelStoreSearchItem

 

index

an index of the item to get, counting from zero

 

Returns

additional read value at index index , or NULL.

[nullable]

Since: 3.58


camel_store_search_thread_item_get_store ()

CamelStore *
camel_store_search_thread_item_get_store
                               (const CamelStoreSearchThreadItem *self);

Gets the CamelStore for the self .

Parameters

Returns

the CamelStore for the self .

[transfer none]

Since: 3.58


camel_store_search_thread_item_get_folder_id ()

guint32
camel_store_search_thread_item_get_folder_id
                               (const CamelStoreSearchThreadItem *self);

Gets the folder ID for the self .

Parameters

Returns

the folder ID for the self

Since: 3.58


camel_store_search_thread_item_get_uid ()

const gchar *
camel_store_search_thread_item_get_uid
                               (const CamelStoreSearchThreadItem *self);

Gets the message UID for the self .

Parameters

Returns

the message UID for the self

Since: 3.58


camel_store_search_thread_item_get_subject ()

const gchar *
camel_store_search_thread_item_get_subject
                               (const CamelStoreSearchThreadItem *self);

Gets the message subject for the self .

Parameters

Returns

the message subject for the self

Since: 3.58


camel_store_search_thread_item_get_message_id ()

guint64
camel_store_search_thread_item_get_message_id
                               (const CamelStoreSearchThreadItem *self);

Gets a hashed value of the Message-ID header for the self .

Parameters

Returns

a hashed value of the Message-ID header for the self

Since: 3.58


camel_store_search_thread_item_get_references ()

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.

Parameters

Returns

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


camel_store_search_index_new ()

CamelStoreSearchIndex *
camel_store_search_index_new (void);

Creates a new CamelStoreSearchIndex. Free it with camel_store_search_index_unref(), when no longer needed.

Returns

a new CamelStoreSearchIndex.

[transfer full]

Since: 3.58


camel_store_search_index_ref ()

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.

Parameters

Returns

the self with added reference.

[transfer full]

Since: 3.58


camel_store_search_index_unref ()

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.

Parameters

self

a CamelStoreSearchIndex.

[transfer full]

Since: 3.58


camel_store_search_index_add ()

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.

Parameters

self

a CamelStoreSearchIndex

 

store

a CamelStore.

[not nullable]

folder_id

a folder ID, other than zero

 

uid

a message UID.

[not nullable]

Since: 3.58


camel_store_search_index_remove ()

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.

Parameters

self

a CamelStoreSearchIndex

 

store

a CamelStore.

[not nullable]

folder_id

a folder ID, other than zero

 

uid

a message UID.

[not nullable]

Returns

whether the message existed and had been removed

Since: 3.58


camel_store_search_index_move_from_existing ()

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.

Parameters

self

a CamelStoreSearchIndex

 

src

a CamelStoreSearchIndex, to move items from

 

Since: 3.58


camel_store_search_index_contains ()

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.

Parameters

self

a CamelStoreSearchIndex

 

store

a CamelStore.

[not nullable]

folder_id

a folder ID, other than zero

 

uid

a message UID.

[not nullable]

Returns

TRUE when the message reference is included in the index self

Since: 3.58


camel_store_search_index_apply_match_threads ()

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.

Parameters

self

a CamelStoreSearchIndex

 

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


camel_store_search_new ()

CamelStoreSearch *
camel_store_search_new (CamelStore *store);

Creates a new CamelStoreSearch, which will operate on folders from the store .

Parameters

store

a CamelStore

 

Returns

a new CamelStoreSearch.

[transfer full]

Since: 3.58


camel_store_search_get_store ()

CamelStore *
camel_store_search_get_store (CamelStoreSearch *self);

Gets a CamelStore the self was constructed for.

Parameters

self

a CamelStoreSearch

 

Returns

a CamelStore the self was constructed for.

[transfer none]

Since: 3.58


camel_store_search_set_expression ()

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.

Parameters

self

a CamelStoreSearch

 

expression

a search expression, or NULL.

[nullable]

Since: 3.58


camel_store_search_get_expression ()

const gchar *
camel_store_search_get_expression (CamelStoreSearch *self);

Gets search expression previously set by the camel_store_search_set_expression().

Parameters

self

a CamelStoreSearch

 

Returns

current search expression for the self , or NULL, when none is set.

[nullable]

Since: 3.58


camel_store_search_set_additional_columns ()

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.

Parameters

self

a CamelStoreSearch

 

colnames

column names, or NULL to unset.

[element-type utf8][nullable]

Since: 3.58


camel_store_search_add_folder ()

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.

Parameters

self

a CamelStoreSearch

 

folder

a CamelFolder

 

Since: 3.58


camel_store_search_remove_folder ()

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.

Parameters

self

a CamelStoreSearch

 

folder

a CamelFolder

 

Since: 3.58


camel_store_search_list_folders ()

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.

Parameters

self

a CamelStoreSearch

 

Returns

a newly created GPtrArray with the CamelFolder instances the self searches in.

[transfer container][element-type CamelFolder]

Since: 3.58


camel_store_search_rebuild_sync ()

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().

Parameters

self

a CamelStoreSearch

 

cancellable

a GCancellable, or NULL

 

error

return location for a GError, or NULL

 

Returns

whether succeeded

Since: 3.58


camel_store_search_get_items_sync ()

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.

Parameters

self

a CamelStoreSearch

 

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 NULL

 

Returns

whether succeeded

Since: 3.58


camel_store_search_get_uids_sync ()

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.

Parameters

self

a CamelStoreSearch

 

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 NULL

 

Returns

whether succeeded

Since: 3.58


camel_store_search_get_match_threads_kind ()

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().

Parameters

self

a CamelStoreSearch

 

out_flags

bit-or of CamelFolderThreadFlags.

[out]

Returns

one of the CamelMatchThreadsKind constants, referencing the requested match-threads search

Since: 3.58


camel_store_search_add_match_threads_items_sync ()

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().

Parameters

self

a CamelStoreSearch

 

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 NULL

 

Returns

whether succeeded; note the inout_items can be still set, even when the call failed

Since: 3.58


camel_store_search_ref_result_index ()

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.

Parameters

self

a CamelStoreSearch

 

Returns

a referenced CamelStoreSearchIndex used as a result index, or NULL, when none is set.

[nullable][transfer full]

Since: 3.58


camel_store_search_set_result_index ()

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.

Parameters

self

a CamelStoreSearch

 

index

a CamelStoreSearchIndex, or NULL.

[nullable][transfer none]

Since: 3.58


camel_store_search_add_match_index ()

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 .

Parameters

self

a CamelStoreSearch

 

index

a CamelStoreSearchIndex to add.

[transfer none]

Since: 3.58


camel_store_search_remove_match_index ()

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.

Parameters

self

a CamelStoreSearch

 

index

a CamelStoreSearchIndex to remove

 

Since: 3.58

Types and Values

CamelStoreSearchItem

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().

Members

guint32 folder_id;

a folder ID

 

const gchar *uid;

a message UID

 

Since: 3.58


struct CamelStoreSearch

struct CamelStoreSearch;

Since: 3.58


CamelStoreSearchIndex

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


CamelStoreSearchItemPrivate

typedef struct _CamelStoreSearchItemPrivate CamelStoreSearchItemPrivate;

CamelStoreSearchThreadItem

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

Property Details

The “store” property

  “store”                    CamelStore *

A CamelStore this search works with.

Owner: CamelStoreSearch

Flags: Read / Write / Construct Only

Since: 3.58