CamelFolderSearch: Camel Reference Manual

## CamelFolderSearch CamelFolderSearch |

## Functions

CamelFolderSearch * | camel_folder_search_new ()
void | camel_folder_search_set_only_cached_messages ()
gboolean | camel_folder_search_get_only_cached_messages ()
void | camel_folder_search_set_current_message_info ()
void | camel_folder_search_take_current_message_info ()
CamelMessageInfo * | camel_folder_search_get_current_message_info ()
GPtrArray * | camel_folder_search_get_current_summary ()
void | camel_folder_search_set_folder ()
CamelFolder * | camel_folder_search_get_folder ()
void | camel_folder_search_set_summary ()
GPtrArray * | camel_folder_search_get_summary ()
gboolean | camel_folder_search_get_summary_empty ()
void | camel_folder_search_set_body_index ()
GPtrArray * | camel_folder_search_search ()
guint32 | camel_folder_search_count ()
void | camel_folder_search_free_result ()
time_t | camel_folder_search_util_add_months ()
time_t | camel_folder_search_util_make_time ()
gint | camel_folder_search_util_compare_date ()
guint64 | camel_folder_search_util_hash_message_id ()

## Object Hierarchy

        GObject
        ╰── CamelFolderSearch
            ╰── CamelIMAPXSearch

## Description

## Functions

### camel_folder_search_new ()

    CamelFolderSearch *
    camel_folder_search_new (void);

Create a new CamelFolderSearch object.

A CamelFolderSearch is a subclassable, extensible s-exp evaluator which enforces a particular set of s-expressions. Particular methods may be overriden by an implementation to implement a search for any sort of backend.

#### Returns

A new CamelFolderSearch intstance.

[transfer full]

### camel_folder_search_set_only_cached_messages ()

    void
    camel_folder_search_set_only_cached_messages
                                   (CamelFolderSearch *search,
                                    gboolean only_cached_messages);

Sets whether only locally cached messages can be searched. The default value is `FALSE`, which means that when a message is required and it is not available locally, then it is downloaded from the server, if possible.

#### Parameters

search | a CamelFolderSearch |
only_cached_messages | a value to set |

Since: 3.24

### camel_folder_search_get_only_cached_messages ()

    gboolean
    camel_folder_search_get_only_cached_messages
                                   (CamelFolderSearch *search);

#### Parameters

search | a CamelFolderSearch |

#### Returns

Whether only cached messages can be searched. See `camel_folder_search_set_only_cached_messages()` for more information what it means.

Since: 3.24

### camel_folder_search_set_current_message_info ()

    void
    camel_folder_search_set_current_message_info
                                   (CamelFolderSearch *search,
                                    CamelMessageInfo *info);

Sets, or unsets, the `info` as the currently processing CamelMessageInfo. The function adds its own reference to `info` , if not `NULL`.

#### Parameters

search | a CamelFolderSearch |
info | a CamelMessageInfo. | [nullable]

Since: 3.24

### camel_folder_search_take_current_message_info ()

    void
    camel_folder_search_take_current_message_info
                                   (CamelFolderSearch *search,
                                    CamelMessageInfo *info);

Sets, or unsets, the `info` as the currently processing CamelMessageInfo. Unlike `camel_folder_search_set_current_message_info()`, this function assumes ownership of the `info` , if not `NULL`.

#### Parameters

search | a CamelFolderSearch |
info | a CamelMessageInfo. | [nullable]

Since: 3.24

### camel_folder_search_get_current_message_info ()

    CamelMessageInfo *
    camel_folder_search_get_current_message_info
                                   (CamelFolderSearch *search);

#### Parameters

search | a CamelFolderSearch |

#### Returns

the currently processing CamelMessageInfo.

[nullable][transfer none]

Since: 3.24

### camel_folder_search_get_current_summary ()

    GPtrArray *
    camel_folder_search_get_current_summary
                                   (CamelFolderSearch *search);

#### Parameters

search | a CamelFolderSearch |

#### Returns

the current summary, and array of message info UID-s to use.

[transfer none][element-type utf8]

Since: 3.24

### camel_folder_search_set_folder ()

    void
    camel_folder_search_set_folder (CamelFolderSearch *search,
                                    CamelFolder *folder);

Set the folder attribute of the search. This can be used to perform a slow-search when indexes and so forth are not available. Or for use by subclasses.

#### Parameters

search | a CamelFolderSearch |
folder | a CamelFolder |

### camel_folder_search_get_folder ()

    CamelFolder *
    camel_folder_search_get_folder (CamelFolderSearch *search);

#### Parameters

search | a CamelFolderSearch |

#### Returns

a CamelFolder for which the `search` is currently running.

[transfer none]

Since: 3.24

### camel_folder_search_set_summary ()

    void
    camel_folder_search_set_summary (CamelFolderSearch *search,
                                     GPtrArray *summary);

Set the array of summary objects representing the span of the search.

If this is not set, then a subclass must provide the functions for searching headers and for the match-all operator.

#### Parameters

search | a CamelFolderSearch |
summary | An array of UID-s of CamelMessageInfo. | [element-type utf8]

### camel_folder_search_get_summary ()

    GPtrArray *
    camel_folder_search_get_summary (CamelFolderSearch *search);

#### Parameters

search | a CamelFolderSearch |

#### Returns

A summary of UID-s of CamelMessageInfo previously set by `camel_folder_search_set_summary()`.

[element-type utf8][transfer none]

Since: 3.24

### camel_folder_search_get_summary_empty ()

    gboolean
    camel_folder_search_get_summary_empty (CamelFolderSearch *search);

#### Parameters

search | a CamelFolderSearch |

#### Returns

Whether the summary (as returned by `camel_folder_search_get_summary()`) is empty. It returns `FALSE` when the summary is set and contains at least one item.

### camel_folder_search_set_body_index ()

    void
    camel_folder_search_set_body_index (CamelFolderSearch *search,
                                        CamelIndex *body_index);

Set the index representing the contents of all messages in this folder. If this is not set, then the folder implementation should sub-class the CamelFolderSearch and provide its own body-contains function.

#### Parameters

search | a CamelFolderSearch |
body_index | a CamelIndex. | [nullable]

### camel_folder_search_search ()

    GPtrArray *
    camel_folder_search_search (CamelFolderSearch *search,
                                const gchar *expr,
                                GPtrArray *uids,
                                GCancellable *cancellable,
                                GError **error);

Run a search. Search must have had Folder already set on it, and it must implement summaries.

#### Parameters

search | a CamelFolderSearch |
expr | a search expression to run |
uids | to search against, NULL for all uid's. | [element-type utf8]
cancellable | a GCancellable |
error | return location for a GError, or `NULL` |

#### Returns

a GPtrArray with matching UIDs, or `NULL` on error. Use `camel_folder_search_free_result()` to free it when no longer needed.

[element-type utf8][transfer full]

### camel_folder_search_count ()

    guint32
    camel_folder_search_count (CamelFolderSearch *search,
                               const gchar *expr,
                               GCancellable *cancellable,
                               GError **error);

Run a search. Search must have had Folder already set on it, and it must implement summaries.

#### Parameters

search | a CamelFolderSearch |
expr | a search expression to run |
cancellable | a GCancellable |
error | return location for a GError, or `NULL` |

#### Returns

Number of messages that match the query.

Since: 2.26

### camel_folder_search_free_result ()

    void
    camel_folder_search_free_result (CamelFolderSearch *search,
                                     GPtrArray *result);

Frees result of `camel_folder_search_search()` call.

#### Parameters

search | a CamelFolderSearch |
result | a result to free. | [element-type utf8][nullable]

### camel_folder_search_util_add_months ()

    time_t
    camel_folder_search_util_add_months (time_t t,
                                         gint months);

Increases time `t` by the given number of months (or decreases, if `months` is negative).

#### Parameters

t | Initial time |
months | number of months to add or subtract |

#### Returns

a new time_t value

Since: 3.2

### camel_folder_search_util_make_time ()

    time_t
    camel_folder_search_util_make_time (gint argc,
                                        CamelSExpResult **argv);

Implementation of 'make-time' function, which expects one argument, a string or an integer, to be converted into time_t.

#### Parameters

argc | number of arguments in `argv` |
argv | array or arguments |

#### Returns

time_t equivalent of the passed in argument, or (time_t) -1 on error.

Since: 3.30

### camel_folder_search_util_compare_date ()

    gint
    camel_folder_search_util_compare_date (gint64 datetime1,
                                           gint64 datetime2);

Compares date portion of the two date-time values, first converted into the local time zone. The returned value is like with `strcmp()`.

#### Parameters

datetime1 | a time_t-like value of the first date-time |
datetime2 | a time_t-like value of the second date-time |

#### Returns

0 when the dates are equal, < 0 when first is before second and > 0 when the first is after the second date

Since: 3.30

### camel_folder_search_util_hash_message_id ()

    guint64
    camel_folder_search_util_hash_message_id
                                   (const gchar *message_id,
                                    gboolean needs_decode);

Calculates a hash of the Message-ID header value `message_id` .

#### Parameters

message_id | a raw Message-ID header value |
needs_decode | whether the `message_id` requires `camel_header_msgid_decode()` first |

#### Returns

hash of the `message_id` , or 0 on any error.

Since: 3.40