Camel.FolderSearch¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`new` ()
class	`util_add_months` (t, months)
class	`util_compare_date` (datetime1, datetime2)
class	`util_hash_message_id` (message_id, needs_decode)
class	`util_make_time` (argc, argv)
	`count` (expr, cancellable)
	`free_result` (result)
	`get_current_message_info` ()
	`get_current_summary` ()
	`get_folder` ()
	`get_only_cached_messages` ()
	`get_summary` ()
	`get_summary_empty` ()
	`search` (expr, uids, cancellable)
	`set_body_index` (body_index)
	`set_current_message_info` (info)
	`set_folder` (folder)
	`set_only_cached_messages` (only_cached_messages)
	`set_summary` (summary)
	`take_current_message_info` (info)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

None

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent	`GObject.Object`	r

Class Details¶

class Camel.FolderSearch(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: Camel.FolderSearchClass

classmethod new()¶

Returns:: A new Camel.FolderSearch intstance.
Return type:: Camel.FolderSearch

Create a new Camel.FolderSearch object.

A Camel.FolderSearch 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.

classmethod util_add_months(t, months)¶

Parameters:

t (int) – Initial time
months (int) – number of months to add or subtract

Returns:

a new #time_t value

Return type:

int

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

New in version 3.2.

classmethod util_compare_date(datetime1, datetime2)¶

Parameters:

datetime1 (int) – a time_t-like value of the first date-time
datetime2 (int) – 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

Return type:

int

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

New in version 3.30.

classmethod util_hash_message_id(message_id, needs_decode)¶

Parameters:

message_id (str) – a raw Message-ID header value
needs_decode (bool) – whether the message_id requires Camel.header_msgid_decode() first

Returns:

hash of the message_id, or 0 on any error.

Return type:

int

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

New in version 3.40.

classmethod util_make_time(argc, argv)¶

Parameters:

argc (int) – number of arguments in argv
argv (Camel.SExpResult) – array or arguments

Returns:

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

Return type:

int

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

New in version 3.30.

count(expr, cancellable)¶

Parameters:

expr (str) – a search expression to run
cancellable (Gio.Cancellable or None) – a Gio.Cancellable

Raises:

GLib.Error

Returns:

Number of messages that match the query.

Return type:

int

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

New in version 2.26.

free_result(result)¶

Parameters:: result ([str] or None) – a result to free

Frees result of Camel.FolderSearch.search() call.

get_current_message_info()¶

Returns:: the currently processing Camel.MessageInfo
Return type:: Camel.MessageInfo or None

New in version 3.24.

get_current_summary()¶

Returns:: the current summary, and array of message info UID-s to use.
Return type:: [str]

New in version 3.24.

get_folder()¶

Returns:: a Camel.Folder for which the self is currently running.
Return type:: Camel.Folder

New in version 3.24.

get_only_cached_messages()¶

Returns:: Whether only cached messages can be searched. See Camel.FolderSearch.set_only_cached_messages() for more information what it means.
Return type:: bool

New in version 3.24.

get_summary()¶

Returns:: A summary of UID-s of Camel.MessageInfo previously set by Camel.FolderSearch.set_summary().
Return type:: [str]

New in version 3.24.

get_summary_empty()¶

Returns:: Whether the summary (as returned by Camel.FolderSearch.get_summary()) is empty. It returns False when the summary is set and contains at least one item.
Return type:: bool

search(expr, uids, cancellable)¶

Parameters:

expr (str) – a search expression to run
uids ([str]) – to search against, None for all uid’s.
cancellable (Gio.Cancellable or None) – a Gio.Cancellable

Raises:

GLib.Error

Returns:

a GLib.PtrArray with matching UIDs, or None on error. Use Camel.FolderSearch.free_result() to free it when no longer needed.

Return type:

[str]

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

set_body_index(body_index)¶

Parameters:: body_index (Camel.Index or None) – a Camel.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 Camel.FolderSearch and provide its own body-contains function.

set_current_message_info(info)¶

Parameters:: info (Camel.MessageInfo or None) – a Camel.MessageInfo

Sets, or unsets, the info as the currently processing Camel.MessageInfo. The function adds its own reference to info, if not None.

New in version 3.24.

set_folder(folder)¶

Parameters:: folder (Camel.Folder) – a Camel.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.

set_only_cached_messages(only_cached_messages)¶

Parameters:: only_cached_messages (bool) – a value to set

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.

New in version 3.24.

set_summary(summary)¶

Parameters:: summary ([str]) – An array of UID-s of Camel.MessageInfo.

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.

take_current_message_info(info)¶

Parameters:: info (Camel.MessageInfo or None) – a Camel.MessageInfo

Sets, or unsets, the info as the currently processing Camel.MessageInfo. Unlike Camel.FolderSearch.set_current_message_info(), this function assumes ownership of the info, if not None.

New in version 3.24.