CamelStoreSearch: Camel Reference Manual

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

| CamelStoreSearchItem
struct | CamelStoreSearch
| CamelStoreSearchIndex
| CamelStoreSearchItemPrivate
| CamelStoreSearchThreadItem

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

self | a CamelStoreSearchItem |

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

self | a CamelStoreSearchThreadItem |

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

self | a CamelStoreSearchThreadItem |

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

self | a CamelStoreSearchThreadItem |

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

self | a CamelStoreSearchThreadItem |

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

self | a CamelStoreSearchThreadItem |

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

self | a CamelStoreSearchThreadItem |

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

self | a CamelStoreSearchIndex |

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