Camel.Folder¶

Subclasses:	`Camel.OfflineFolder`, `Camel.VeeFolder`

Methods¶

Inherited:	Camel.Object (4), GObject.Object (37)
Structs:	GObject.ObjectClass (5)

class	`error_quark` ()
class	`threaded_messages_dump` (c)
	`append_message` (message, info, io_priority, cancellable, callback, *user_data)
	`append_message_finish` (result, appended_uid)
	`append_message_sync` (message, info, appended_uid, cancellable)
	`changed` (changes)
	`cmp_uids` (uid1, uid2)
	`count_by_expression` (expression, cancellable)
	`delete` ()
	`dup_description` ()
	`dup_display_name` ()
	`dup_full_name` ()
	`expunge` (io_priority, cancellable, callback, *user_data)
	`expunge_finish` (result)
	`expunge_sync` (cancellable)
	`free_deep` (array)
	`free_shallow` (array)
	`free_summary` (array)
	`free_uids` (array)
	`freeze` ()
	`get_deleted_message_count` ()
	`get_description` ()
	`get_display_name` ()
	`get_filename` (uid)
	`get_flags` ()
	`get_folder_summary` ()
	`get_frozen_count` ()
	`get_full_name` ()
	`get_mark_seen` ()
	`get_mark_seen_timeout` ()
	`get_message` (message_uid, io_priority, cancellable, callback, *user_data)
	`get_message_cached` (message_uid, cancellable)
	`get_message_count` ()
	`get_message_finish` (result)
	`get_message_flags` (uid)
	`get_message_info` (uid)
	`get_message_sync` (message_uid, cancellable)
	`get_message_user_flag` (uid, name)
	`get_message_user_tag` (uid, name)
	`get_parent_store` ()
	`get_permanent_flags` ()
	`get_quota_info` (io_priority, cancellable, callback, *user_data)
	`get_quota_info_finish` (result)
	`get_quota_info_sync` (cancellable)
	`get_summary` ()
	`get_uids` ()
	`get_uncached_uids` (uids)
	`get_unread_message_count` ()
	`has_summary_capability` ()
	`is_frozen` ()
	`lock` ()
	`prepare_content_refresh` ()
	`purge_message_cache` (start_uid, end_uid, io_priority, cancellable, callback, *user_data)
	`purge_message_cache_finish` (result)
	`purge_message_cache_sync` (start_uid, end_uid, cancellable)
	`refresh_info` (io_priority, cancellable, callback, *user_data)
	`refresh_info_finish` (result)
	`refresh_info_sync` (cancellable)
	`rename` (new_name)
	`search_by_expression` (expression, cancellable)
	`search_by_uids` (expression, uids, cancellable)
	`search_free` (result)
	`set_description` (description)
	`set_display_name` (display_name)
	`set_flags` (folder_flags)
	`set_full_name` (full_name)
	`set_lock_async` (skip_folder_lock)
	`set_mark_seen` (mark_seen)
	`set_mark_seen_timeout` (timeout)
	`set_message_flags` (uid, mask, set)
	`set_message_user_flag` (uid, name, value)
	`set_message_user_tag` (uid, name, value)
	`sort_uids` (uids)
	`synchronize` (expunge, io_priority, cancellable, callback, *user_data)
	`synchronize_finish` (result)
	`synchronize_message` (message_uid, io_priority, cancellable, callback, *user_data)
	`synchronize_message_finish` (result)
	`synchronize_message_sync` (message_uid, cancellable)
	`synchronize_sync` (expunge, cancellable)
	`take_folder_summary` (summary)
	`thaw` ()
	`transfer_messages_to` (message_uids, destination, delete_originals, io_priority, cancellable, callback, *user_data)
	`transfer_messages_to_finish` (result)
	`transfer_messages_to_sync` (message_uids, destination, delete_originals, cancellable)
	`unlock` ()

Virtual Methods¶

Inherited:	Camel.Object (2), GObject.Object (7)

	`do_append_message_sync` (message, info, appended_uid, cancellable)
	`do_changed` (changes)
	`do_cmp_uids` (uid1, uid2)
	`do_count_by_expression` (expression, cancellable)
	`do_delete_` ()
	`do_deleted` ()
	`do_expunge_sync` (cancellable)
	`do_free_summary` (array)
	`do_free_uids` (array)
	`do_freeze` ()
	`do_get_filename` (uid)
	`do_get_message_cached` (message_uid, cancellable)
	`do_get_message_count` ()
	`do_get_message_flags` (uid)
	`do_get_message_info` (uid)
	`do_get_message_sync` (message_uid, cancellable)
	`do_get_message_user_flag` (uid, name)
	`do_get_message_user_tag` (uid, name)
	`do_get_permanent_flags` ()
	`do_get_quota_info_sync` (cancellable)
	`do_get_summary` ()
	`do_get_uids` ()
	`do_get_uncached_uids` (uids)
	`do_has_search_capability` ()
	`do_is_frozen` ()
	`do_prepare_content_refresh` ()
	`do_purge_message_cache_sync` (start_uid, end_uid, cancellable)
	`do_refresh_info_sync` (cancellable)
	`do_rename` (new_name)
	`do_renamed` (old_name)
	`do_search_by_expression` (expression, cancellable)
	`do_search_by_uids` (expression, uids, cancellable)
	`do_search_free` (result)
	`do_set_message_flags` (uid, mask, set)
	`do_set_message_user_flag` (uid, name, value)
	`do_set_message_user_tag` (uid, name, value)
	`do_sort_uids` (uids)
	`do_synchronize_message_sync` (message_uid, cancellable)
	`do_synchronize_sync` (expunge, cancellable)
	`do_thaw` ()
	`do_transfer_messages_to_sync` (message_uids, destination, delete_originals, cancellable)

Properties¶

Inherited:	Camel.Object (1)

Name	Type	Flags	Short Description
`description`	`str`	r/w/c/en	The folder’s description
`display-name`	`str`	r/w/c/en	The folder’s display name
`full-name`	`str`	r/w/c/en	The folder’s fully qualified name
`mark-seen`	`Camel.ThreeState`	r/w/c/en	Mark messages as read after N seconds
`mark-seen-timeout`	`int`	r/w/c/en	Mark seen timeout
`parent-store`	`Camel.Store`	r/w/co	The store to which the folder belongs

Signals¶

Inherited:	GObject.Object (1)

Name	Short Description
`changed`
`deleted`
`renamed`

Fields¶

Inherited:	GObject.Object (1)

Name	Type	Access	Description
parent	`Camel.Object`	r

Class Details¶

class Camel.Folder(**kwargs)¶

Bases:	`Camel.Object`
Abstract:	Yes
Structure:	`Camel.FolderClass`

classmethod error_quark()¶

Return type:	`int`

classmethod threaded_messages_dump(c)¶

Parameters:	c (`Camel.FolderThreadNode`) –
Return type:	`int`

append_message(message, info, io_priority, cancellable, callback, *user_data)¶

Parameters:

message (Camel.MimeMessage) – a Camel.MimeMessage
info (Camel.MessageInfo) – a Camel.MessageInfo with additional flags/etc to set on the new message, or None
io_priority (int) – the I/O priority of the request
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the request is satisfied
user_data (object or None) – data to pass to the callback function

Appends message to self asynchronously. Only the flag and tag data from info are used. If info is None, no flags or tags will be set.

When the operation is finished, callback will be called. You can then call Camel.Folder.append_message_finish() to get the result of the operation.

New in version 3.0.

append_message_finish(result, appended_uid)¶

Parameters:	result (`Gio.AsyncResult`) – a `Gio.AsyncResult` appended_uid (`str`) – if non-`None`, the UID of the appended message will be returned here, if it is known
Raises:	`GLib.Error`
Returns:	`True` on success, `False` on error
Return type:	`bool`

Finishes the operation started with Camel.Folder.append_message_finish().

New in version 3.0.

append_message_sync(message, info, appended_uid, cancellable)¶

Parameters:	message (`Camel.MimeMessage`) – a `Camel.MimeMessage` info (`Camel.MessageInfo`) – a `Camel.MessageInfo` with additional flags/etc to set on the new message, or `None` appended_uid (`str`) – if non-`None`, the UID of the appended message will be returned here, if it is known cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Raises:	`GLib.Error`
Returns:	`True` on success, `False` on error
Return type:	`bool`

Appends message to self. Only the flag and tag data from info are used. If info is None, no flags or tags will be set.

New in version 3.0.

changed(changes)¶

Parameters:	changes (`Camel.FolderChangeInfo`) – change information for self

Emits the Camel.Folder ::changed signal from an idle source on the main loop. The idle source’s priority is GLib.PRIORITY_LOW.

New in version 2.32.

cmp_uids(uid1, uid2)¶

Parameters:	uid1 (`str`) – The first uid. uid2 (`str`) – the second uid.
Return type:	`int`

Compares two uids. The return value meaning is the same as in any other compare function.

Note that the default compare function expects a decimal number at the beginning of a uid, thus if provider uses different uid values, then it should subclass this function.

New in version 2.28.

count_by_expression(expression, cancellable)¶

Parameters:	expression (`str`) – a search expression cancellable (`Gio.Cancellable` or `None`) – a `Gio.Cancellable`
Raises:	`GLib.Error`
Returns:	an interger
Return type:	`int`

Searches the folder for count of messages matching the given search expression.

New in version 2.26.

delete()¶

Marks self as deleted and performs any required cleanup.

This also emits the Camel.Folder ::deleted signal from an idle source on the main loop. The idle source’s priority is GLib.PRIORITY_HIGH_IDLE.

dup_description()¶

Returns:	a newly-allocated copy of `Camel.Folder` `:description`
Return type:	`str`

Thread-safe variation of Camel.Folder.get_description(). Use this function when accessing self from multiple threads.

The returned string should be freed with GLib.free() when no longer needed.

New in version 3.8.

dup_display_name()¶

Returns:	a newly-allocated copy of `Camel.Folder` `:display-name`
Return type:	`str`

Thread-safe variation of Camel.Folder.get_display_name(). Use this function when accessing self from multiple threads.

The returned string should be freed with GLib.free() when no longer needed.

New in version 3.8.

dup_full_name()¶

Returns:	a newly-allocated copy of `Camel.Folder` `:full-name`
Return type:	`str`

Thread-safe variation of Camel.Folder.get_full_name(). Use this function when accessing self from multiple threads.

The returned string should be freed with GLib.free() when no longer needed.

New in version 3.8.

expunge(io_priority, cancellable, callback, *user_data)¶

Parameters:	io_priority (`int`) – the I/O priority of the request cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None` callback (`Gio.AsyncReadyCallback` or `None`) – a `Gio.AsyncReadyCallback` to call when the request is satisfied user_data (`object` or `None`) – data to pass to the callback function

Asynchronously deletes messages which have been marked as “DELETED”.

When the operation is finished, callback will be called. You can then call Camel.Folder.expunge_finish() to get the result of the operation.

New in version 3.0.

expunge_finish(result)¶

Parameters:	result (`Gio.AsyncResult`) – a `Gio.AsyncResult`
Raises:	`GLib.Error`
Returns:	`True` on success, `False` on error
Return type:	`bool`

Finishes the operation started with Camel.Folder.expunge().

New in version 3.0.

expunge_sync(cancellable)¶

Parameters:	cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Raises:	`GLib.Error`
Returns:	`True` on success, `False` on error
Return type:	`bool`

Deletes messages which have been marked as “DELETED”.

New in version 3.0.

free_deep(array)¶

Parameters:	array ([`str`]) – an array of uids

Frees the provided array and its contents. Used by Camel.Folder subclasses as an implementation for free_uids when the provided information was created explicitly by the corresponding get_ call.

free_shallow(array)¶

Parameters:	array ([`str`]) – an array of uids or `Camel.MessageInfo`

Frees the provided array but not its contents. Used by Camel.Folder subclasses as an implementation for free_uids or free_summary when the returned array needs to be freed but its contents come from “static” information.

free_summary(array)¶

Parameters:	array ([`Camel.MessageInfo`]) – the summary array to free

Frees the summary array returned by Camel.Folder.get_summary().

free_uids(array)¶

Parameters:	array ([`str`]) – the array of uids to free

Frees the array of UIDs returned by Camel.Folder.get_uids().

freeze()¶: Freezes the folder so that a series of operation can be performed without “folder_changed” signals being emitted. When the folder is later thawed with Camel.Folder.thaw(), the suppressed signals will be emitted.

get_deleted_message_count()¶

Returns:	the number of deleted messages in the folder, or -1 if unknown
Return type:	`int`

get_description()¶

Returns:	a description of the folder
Return type:	`str`

Returns a description of the folder suitable for displaying to the user.

New in version 2.32.

get_display_name()¶

Returns:	the display name of the folder
Return type:	`str`

Returns the display name for the folder. The fully qualified name can be obtained with Camel.Folder.get_full_name().

New in version 3.2.

get_filename(uid)¶

Parameters:	uid (`str`) – a message UID
Raises:	`GLib.Error`
Returns:	a file name corresponding to a message with UID uid. Free the returned string with `GLib.free`(), when no longer needed.
Return type:	`str`

New in version 2.26.

get_flags()¶

Returns:	Folder flags (bit-or of `Camel.FolderFlags`) of the self
Return type:	`int`

New in version 3.24.

get_folder_summary()¶

Returns:	a `Camel.FolderSummary` of the folder
Return type:	`Camel.FolderSummary`

New in version 3.24.

get_frozen_count()¶

Return type:	`int`

New in version 2.32.

get_full_name()¶

Returns:	the fully qualified name of the folder
Return type:	`str`

Returns the fully qualified name of the folder.

get_mark_seen()¶

Returns:	a `Camel.ThreeState`, whether messages in this self should be marked as seen automatically.
Return type:	`Camel.ThreeState`

New in version 3.32.

get_mark_seen_timeout()¶

Returns:	timeout in milliseconds for marking messages as seen in this self
Return type:	`int`

New in version 3.32.

get_message(message_uid, io_priority, cancellable, callback, *user_data)¶

Parameters:	message_uid (`str`) – the message UID io_priority (`int`) – the I/O priority of the request cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None` callback (`Gio.AsyncReadyCallback` or `None`) – a `Gio.AsyncReadyCallback` to call when the request is satisfied user_data (`object` or `None`) – data to pass to the callback function

Asynchronously gets the message corresponding to message_uid from self.

When the operation is finished, callback will be called. You can then call Camel.Folder.get_message_finish() to get the result of the operation.

New in version 3.0.

get_message_cached(message_uid, cancellable)¶

Parameters:	message_uid (`str`) – the message UID cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Returns:	a cached `Camel.MimeMessage` corresponding to the requested UID
Return type:	`Camel.MimeMessage` or `None`

Gets the message corresponding to message_uid from the self cache, if available locally. This should not do any network I/O, only check if message is already downloaded and return it quickly, not being blocked by the folder’s lock. Returning None is not considered as an error, it just means that the message is still to-be-downloaded.

Note: This function is called automatically within Camel.Folder.get_message_sync().

New in version 3.24.

get_message_count()¶

Returns:	the number of messages in the folder, or -1 if unknown
Return type:	`int`

get_message_finish(result)¶

Parameters:	result (`Gio.AsyncResult`) – a `Gio.AsyncResult`
Raises:	`GLib.Error`
Returns:	a `Camel.MimeMessage` corresponding to the requested UID
Return type:	`Camel.MimeMessage`

Finishes the operation started with Camel.Folder.get_message().

New in version 3.0.

get_message_flags(uid)¶

Parameters:	uid (`str`) – the UID of a message in self
Returns:	the `Camel.MessageFlags` that are set on the indicated message.
Return type:	`int`

Deprecated since version ???: Use Camel.Folder.get_message_info() instead.

get_message_info(uid)¶

Parameters:	uid (`str`) – the uid of a message
Returns:	The summary information for the indicated message, or `None` if the uid does not exist. Free the returned object with `GObject.Object.unref`(), when done with it.
Return type:	`Camel.MessageInfo`

Retrieve the Camel.MessageInfo for the specified uid.

get_message_sync(message_uid, cancellable)¶

Parameters:	message_uid (`str`) – the message UID cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Raises:	`GLib.Error`
Returns:	a `Camel.MimeMessage` corresponding to the requested UID
Return type:	`Camel.MimeMessage`

Gets the message corresponding to message_uid from self.

New in version 3.0.

get_message_user_flag(uid, name)¶

Parameters:	uid (`str`) – the UID of a message in self name (`str`) – the name of a user flag
Returns:	`True` if the given user flag is set on the message or `False` otherwise
Return type:	`bool`

Deprecated since version ???: Use Camel.MessageInfo.get_user_flag() on the message info directly

get_message_user_tag(uid, name)¶

Parameters:	uid (`str`) – the UID of a message in self name (`str`) – the name of a user tag
Returns:	the value of the user tag
Return type:	`str`

Deprecated since version ???: Use Camel.MessageInfo.get_user_tag() on the Camel.MessageInfo directly.

get_parent_store()¶

Returns:	the parent `Camel.Store` of the folder
Return type:	`object` or `None`

get_permanent_flags()¶

Returns:	the set of `Camel.MessageFlags` that can be permanently stored on a message between sessions. If it includes `Camel.MessageFlags.USER`, then user-defined flags will be remembered.
Return type:	`int`

get_quota_info(io_priority, cancellable, callback, *user_data)¶

Parameters:	io_priority (`int`) – the I/O priority of the request cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None` callback (`Gio.AsyncReadyCallback` or `None`) – a `Gio.AsyncReadyCallback` to call when the request is satisfied user_data (`object` or `None`) – data to pass to the callback function

Asynchronously gets a list of known quotas for self.

When the operation is finished, callback will be called. You can then call Camel.Folder.get_quota_info_finish() to get the result of the operation.

New in version 3.2.

get_quota_info_finish(result)¶

Parameters:	result (`Gio.AsyncResult`) – a `Gio.AsyncResult`
Raises:	`GLib.Error`
Returns:	a `Camel.FolderQuotaInfo`, or `None`
Return type:	`Camel.FolderQuotaInfo`

Finishes the operation started with Camel.Folder.get_quota_info(). Free the returned Camel.FolderQuotaInfo struct with Camel.FolderQuotaInfo.free().

If quotas are not supported for self, the function returns None and sets error to Gio.IOErrorEnum.NOT_SUPPORTED.

New in version 3.2.

get_quota_info_sync(cancellable)¶

Parameters:	cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Raises:	`GLib.Error`
Returns:	a `Camel.FolderQuotaInfo`, or `None`
Return type:	`Camel.FolderQuotaInfo`

Gets a list of known quotas for self. Free the returned Camel.FolderQuotaInfo struct with Camel.FolderQuotaInfo.free().

If quotas are not supported for self, the function returns None and sets error to Gio.IOErrorEnum.NOT_SUPPORTED.

New in version 3.2.

get_summary()¶

Returns:	an array of UID-s of `Camel.MessageInfo`
Return type:	[`str`]

This returns the summary information for the folder. This array should not be modified, and must be freed with Camel.Folder.free_summary().

get_uids()¶

Returns:	a `GLib.PtrArray` of UIDs corresponding to the messages available in the folder
Return type:	[`str`]

Get the list of UIDs available in a folder. This routine is useful for finding what messages are available when the folder does not support summaries. The returned array should not be modified, and must be freed by passing it to Camel.Folder.free_uids().

get_uncached_uids(uids)¶

Parameters:	uids ([`str`]) – the array of uids to filter down to uncached ones.
Raises:	`GLib.Error`
Return type:	[`str`]

Returns the known-uncached uids from a list of uids. It may return uids which are locally cached but should never filter out a uid which is not locally cached. Free the result by called Camel.Folder.free_uids(). Frees the array of UIDs returned by Camel.Folder.get_uids().

New in version 2.26.

get_unread_message_count()¶

Returns:	the number of unread messages in the folder, or -1 if unknown
Return type:	`int`

Deprecated since version ???: use Camel.FolderSummary.get_unread_count() instead.

has_summary_capability()¶

Returns:	`True` if a summary is available or `False` otherwise
Return type:	`bool`

Get whether or not the folder has a summary.

is_frozen()¶

Returns:	whether or not the folder is frozen
Return type:	`bool`

lock()¶: Locks self. Unlock it with Camel.Folder.unlock().

New in version 2.32.

prepare_content_refresh()¶: Lets the self know that it should refresh its content the next time from fresh. This is useful for remote accounts, to fully re-check the folder content against the server.

New in version 3.22.

purge_message_cache(start_uid, end_uid, io_priority, cancellable, callback, *user_data)¶

Parameters:

start_uid (str) – the start message UID
end_uid (str) – the end message UID
io_priority (int) – the I/O priority of the request
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the request is satisfied
user_data (object or None) – data to pass to the callback function

Delete the local cache of all messages between these uids.

When the operation is finished, callback will be called. You can then call Camel.Folder.purge_message_cache_finish() to get the result of the operation.

New in version 3.4.

purge_message_cache_finish(result)¶

Parameters:	result (`Gio.AsyncResult`) – a `Gio.AsyncResult`
Raises:	`GLib.Error`
Returns:	`True` on success, `False` on failure
Return type:	`bool`

Finishes the operation started with Camel.Folder.purge_message_cache().

New in version 3.4.

purge_message_cache_sync(start_uid, end_uid, cancellable)¶

Parameters:	start_uid (`str`) – the start message UID end_uid (`str`) – the end message UID cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Raises:	`GLib.Error`
Returns:	`True` on success, `False` on failure
Return type:	`bool`

Delete the local cache of all messages between these uids.

New in version 3.4.

refresh_info(io_priority, cancellable, callback, *user_data)¶

Parameters:	io_priority (`int`) – the I/O priority of the request cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None` callback (`Gio.AsyncReadyCallback` or `None`) – a `Gio.AsyncReadyCallback` to call when the request is satisfied user_data (`object` or `None`) – data to pass to the callback function

Asynchronously synchronizes a folder’s summary with its backing store.

When the operation is finished, callback will be called. You can then call Camel.Folder.refresh_info_finish() to get the result of the operation.

New in version 3.2.

refresh_info_finish(result)¶

Parameters:	result (`Gio.AsyncResult`) – a `Gio.AsyncResult`
Raises:	`GLib.Error`
Returns:	`True` on success, `False` on error
Return type:	`bool`

Finishes the operation started with Camel.Folder.refresh_info().

New in version 3.2.

refresh_info_sync(cancellable)¶

Parameters:	cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Raises:	`GLib.Error`
Returns:	`True` on success, `False` on error
Return type:	`bool`

Synchronizes a folder’s summary with its backing store.

New in version 3.0.

rename(new_name)¶

Parameters:	new_name (`str`) – new name for the folder

Marks self as renamed.

This also emits the Camel.Folder ::renamed signal from an idle source on the main loop. The idle source’s priority is GLib.PRIORITY_HIGH_IDLE.

NOTE: This is an internal function used by camel stores, no locking is performed on the folder.

search_by_expression(expression, cancellable)¶

Parameters:	expression (`str`) – a search expression cancellable (`Gio.Cancellable` or `None`) – a `Gio.Cancellable`
Raises:	`GLib.Error`
Returns:	a `GLib.PtrArray` of uids of matching messages. The caller must free the list and each of the elements when it is done.
Return type:	[`str`]

Searches the folder for messages matching the given search expression.

search_by_uids(expression, uids, cancellable)¶

Parameters:	expression (`str`) – search expression uids ([`str`]) – array of uid’s to match against. cancellable (`Gio.Cancellable` or `None`) – a `Gio.Cancellable`
Raises:	`GLib.Error`
Returns:	a `GLib.PtrArray` of uids of matching messages. The caller must free the list and each of the elements when it is done.
Return type:	[`str`]

Search a subset of uid’s for an expression match.

search_free(result)¶

Parameters:	result ([`str`]) – search results to free

Free the result of a search as gotten by Camel.Folder.search_by_expression() or Camel.Folder.search_by_uids().

set_description(description)¶

Parameters:	description (`str`) – a description of the folder

Sets a description of the folder suitable for displaying to the user.

New in version 2.32.

set_display_name(display_name)¶

Parameters:	display_name (`str`) – a display name for the folder

Sets the display name for the folder.

New in version 3.2.

set_flags(folder_flags)¶

Parameters:	folder_flags (`int`) – flags (bit-or of `Camel.FolderFlags`) to set

Sets folder flags (bit-or of Camel.FolderFlags) for the self.

New in version 3.24.

set_full_name(full_name)¶

Parameters:	full_name (`str`) – a fully qualified name for the folder

Sets the fully qualified name of the folder.

New in version 2.32.

set_lock_async(skip_folder_lock)¶

Parameters:	skip_folder_lock (`bool`) – a value to set

Sets whether folder locking (Camel.Folder.lock() and Camel.Folder.unlock()) should be used. When set to False, the two functions do nothing and simply return.

New in version 2.30.

set_mark_seen(mark_seen)¶

Parameters:	mark_seen (`Camel.ThreeState`) – a `Camel.ThreeState` as the value to set

Sets whether the messages in this self should be marked as seen automatically. An inconsistent state means to use global option.

New in version 3.32.

set_mark_seen_timeout(timeout)¶

Parameters:	timeout (`int`) – a timeout in milliseconds

Sets the timeout in milliseconds for marking messages as seen in this self. Whether the timeout is used depends on Camel.Folder.get_mark_seen().

New in version 3.32.

set_message_flags(uid, mask, set)¶

Parameters:	uid (`str`) – the UID of a message in self mask (`int`) – a mask of `Camel.MessageFlags` bit-or values to use set (`int`) – the flags to ser, also bit-or of `Camel.MessageFlags`
Returns:	`True` if the flags were changed or `False` otherwise
Return type:	`bool`

Sets those flags specified by mask to the values specified by set on the indicated message. (This may or may not persist after the folder or store is closed. See Camel.Folder.get_permanent_flags())

E.g. to set the deleted flag and clear the draft flag, use Camel.Folder.set_message_flags (folder, uid, Camel.MessageFlags.DELETED|:obj:Camel.MessageFlags.DRAFT, Camel.MessageFlags.DELETED);

Deprecated since version ???: Use Camel.MessageInfo.set_flags() on the message info directly (when it works)

set_message_user_flag(uid, name, value)¶

Parameters:	uid (`str`) – the UID of a message in self name (`str`) – the name of the user flag to set value (`bool`) – the value to set it to

Deprecated since version ???: Use Camel.MessageInfo.set_user_flag() on the Camel.MessageInfo directly (when it works) Sets the user flag specified by name to the value specified by value on the indicated message. (This may or may not persist after the folder or store is closed. See Camel.Folder.get_permanent_flags())

set_message_user_tag(uid, name, value)¶

Parameters:	uid (`str`) – the UID of a message in self name (`str`) – the name of the user tag to set value (`str`) – the value to set it to

Deprecated since version ???: Use Camel.MessageInfo.set_user_tag() on the Camel.MessageInfo directly (when it works). Sets the user tag specified by name to the value specified by value on the indicated message. (This may or may not persist after the folder or store is closed. See Camel.Folder.get_permanent_flags())

sort_uids(uids)¶

Parameters:	uids ([`str`]) – array of uids

Sorts the array of UIDs.

New in version 2.24.

synchronize(expunge, io_priority, cancellable, callback, *user_data)¶

Parameters:

expunge (bool) – whether to expunge after synchronizing
io_priority (int) – the I/O priority of the request
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the request is satisfied
user_data (object or None) – data to pass to the callback function

Synchronizes any changes that have been made to self to its backing store asynchronously, optionally expunging deleted messages as well.

When the operation is finished, callback will be called. You can then call Camel.Folder.synchronize_finish() to get the result of the operation.

New in version 3.0.

synchronize_finish(result)¶

Parameters:	result (`Gio.AsyncResult`) – a `Gio.AsyncResult`
Raises:	`GLib.Error`
Returns:	`True` on sucess, `False` on error
Return type:	`bool`

Finishes the operation started with Camel.Folder.synchronize().

New in version 3.0.

synchronize_message(message_uid, io_priority, cancellable, callback, *user_data)¶

Parameters:	message_uid (`str`) – a message UID io_priority (`int`) – the I/O priority of the request cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None` callback (`Gio.AsyncReadyCallback` or `None`) – a `Gio.AsyncReadyCallback` to call when the request is satisfied user_data (`object` or `None`) – data to pass to the callback function

Asynchronously ensure that a message identified by message_uid has been synchronized in self so that calling Camel.Folder.get_message() on it later will work in offline mode.

When the operation is finished, callback will be called. You can then call Camel.Folder.synchronize_message_finish() to get the result of the operation.

New in version 3.0.

synchronize_message_finish(result)¶

Parameters:	result (`Gio.AsyncResult`) – a `Gio.AsyncResult`
Raises:	`GLib.Error`
Returns:	`True` on success, `False` on error
Return type:	`bool`

Finishes the operation started with Camel.Folder.synchronize_message().

New in version 3.0.

synchronize_message_sync(message_uid, cancellable)¶

Parameters:	message_uid (`str`) – a message UID cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Raises:	`GLib.Error`
Returns:	`True` on success, `False` on error
Return type:	`bool`

Ensure that a message identified by message_uid has been synchronized in self so that calling Camel.Folder.get_message() on it later will work in offline mode.

New in version 3.0.

synchronize_sync(expunge, cancellable)¶

Parameters:	expunge (`bool`) – whether to expunge after synchronizing cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Raises:	`GLib.Error`
Returns:	`True` on success, `False` on error
Return type:	`bool`

Synchronizes any changes that have been made to self to its backing store, optionally expunging deleted messages as well.

New in version 3.0.

take_folder_summary(summary)¶

Parameters:	summary (`Camel.FolderSummary`) – a `Camel.FolderSummary`

Sets a Camel.FolderSummary of the folder. It consumes the summary.

This is supposed to be called only by the descendants of the Camel.Folder and only at the construction time. Calling this function twice yeilds to an error.

New in version 3.24.

thaw()¶: Thaws the folder and emits any pending folder_changed signals.

transfer_messages_to(message_uids, destination, delete_originals, io_priority, cancellable, callback, *user_data)¶

Parameters:

message_uids ([str]) – message UIDs in self
destination (Camel.Folder) – the destination Camel.Folder
delete_originals (bool) – whether or not to delete the original messages
io_priority (int) – the I/O priority of the request
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the request is satisfied
user_data (object or None) – data to pass to the callback function

Asynchronously copies or moves messages from one folder to another. If the self or destination folders have the same parent store, this may be more efficient than using Camel.Folder.append_message().

When the operation is finished, callback will be called. You can then call Camel.Folder.transfer_messages_to_finish() to get the result of the operation.

New in version 3.0.

transfer_messages_to_finish(result)¶

Parameters: result (Gio.AsyncResult) – a Gio.AsyncResult

Raises: GLib.Error

Returns:

True on success, False on error

transferred_uids:
	if non-`None`, the UIDs of the resulting messages in destination will be stored here, if known.

Return type: (bool, transferred_uids: [str])

Finishes the operation started with Camel.Folder.transfer_messages_to().

New in version 3.0.

transfer_messages_to_sync(message_uids, destination, delete_originals, cancellable)¶

Parameters:

message_uids ([str]) – message UIDs in self
destination (Camel.Folder) – the destination Camel.Folder
delete_originals (bool) – whether or not to delete the original messages
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

True on success, False on failure

transferred_uids:
	if non-`None`, the UIDs of the resulting messages in destination will be stored here, if known.

Return type:

(bool, transferred_uids: [str])

Copies or moves messages from one folder to another. If the self and destination folders have the same parent_store, this may be more efficient than using Camel.Folder.append_message_sync().

New in version 3.0.

unlock()¶: Unlocks self, previously locked with Camel.Folder.lock().

New in version 2.32.

do_append_message_sync(message, info, appended_uid, cancellable) virtual¶

Parameters:	message (`Camel.MimeMessage`) – a `Camel.MimeMessage` info (`Camel.MessageInfo`) – a `Camel.MessageInfo` with additional flags/etc to set on the new message, or `None` appended_uid (`str`) – if non-`None`, the UID of the appended message will be returned here, if it is known cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Returns:	`True` on success, `False` on error
Return type:	`bool`

Appends message to folder. Only the flag and tag data from info are used. If info is None, no flags or tags will be set.

New in version 3.0.

do_changed(changes) virtual¶

Parameters:	changes (`Camel.FolderChangeInfo`) – change information for folder

Emits the Camel.Folder ::changed signal from an idle source on the main loop. The idle source’s priority is GLib.PRIORITY_LOW.

New in version 2.32.

do_cmp_uids(uid1, uid2) virtual¶

Parameters:	uid1 (`str`) – The first uid. uid2 (`str`) – the second uid.
Return type:	`int`

Compares two uids. The return value meaning is the same as in any other compare function.

Note that the default compare function expects a decimal number at the beginning of a uid, thus if provider uses different uid values, then it should subclass this function.

New in version 2.28.

do_count_by_expression(expression, cancellable) virtual¶

Parameters:	expression (`str`) – a search expression cancellable (`Gio.Cancellable` or `None`) – a `Gio.Cancellable`
Returns:	an interger
Return type:	`int`

Searches the folder for count of messages matching the given search expression.

New in version 2.26.

do_delete_() virtual¶

do_deleted() virtual¶

do_expunge_sync(cancellable) virtual¶

Parameters:	cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Returns:	`True` on success, `False` on error
Return type:	`bool`

Deletes messages which have been marked as “DELETED”.

New in version 3.0.

do_free_summary(array) virtual¶

Parameters:	array ([`Camel.MessageInfo`]) – the summary array to free

Frees the summary array returned by Camel.Folder.get_summary().

do_free_uids(array) virtual¶

Parameters:	array ([`str`]) – the array of uids to free

Frees the array of UIDs returned by Camel.Folder.get_uids().

do_freeze() virtual¶: Freezes the folder so that a series of operation can be performed without “folder_changed” signals being emitted. When the folder is later thawed with Camel.Folder.thaw(), the suppressed signals will be emitted.

do_get_filename(uid) virtual¶

Parameters:	uid (`str`) – a message UID
Returns:	a file name corresponding to a message with UID uid. Free the returned string with `GLib.free`(), when no longer needed.
Return type:	`str`

New in version 2.26.

do_get_message_cached(message_uid, cancellable) virtual¶

Parameters:	message_uid (`str`) – the message UID cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Returns:	a cached `Camel.MimeMessage` corresponding to the requested UID
Return type:	`Camel.MimeMessage` or `None`

Gets the message corresponding to message_uid from the folder cache, if available locally. This should not do any network I/O, only check if message is already downloaded and return it quickly, not being blocked by the folder’s lock. Returning None is not considered as an error, it just means that the message is still to-be-downloaded.

Note: This function is called automatically within Camel.Folder.get_message_sync().

New in version 3.24.

do_get_message_count() virtual¶

Returns:	the number of messages in the folder, or -1 if unknown
Return type:	`int`

do_get_message_flags(uid) virtual¶

Parameters:	uid (`str`) – the UID of a message in folder
Returns:	the `Camel.MessageFlags` that are set on the indicated message.
Return type:	`int`

Deprecated since version ???: Use Camel.Folder.get_message_info() instead.

do_get_message_info(uid) virtual¶

Parameters:	uid (`str`) – the uid of a message
Returns:	The summary information for the indicated message, or `None` if the uid does not exist. Free the returned object with `GObject.Object.unref`(), when done with it.
Return type:	`Camel.MessageInfo`

Retrieve the Camel.MessageInfo for the specified uid.

do_get_message_sync(message_uid, cancellable) virtual¶

Parameters:	message_uid (`str`) – the message UID cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Returns:	a `Camel.MimeMessage` corresponding to the requested UID
Return type:	`Camel.MimeMessage`

Gets the message corresponding to message_uid from folder.

New in version 3.0.

do_get_message_user_flag(uid, name) virtual¶

Parameters:	uid (`str`) – the UID of a message in folder name (`str`) – the name of a user flag
Returns:	`True` if the given user flag is set on the message or `False` otherwise
Return type:	`bool`

Deprecated since version ???: Use Camel.MessageInfo.get_user_flag() on the message info directly

do_get_message_user_tag(uid, name) virtual¶

Parameters:	uid (`str`) – the UID of a message in folder name (`str`) – the name of a user tag
Returns:	the value of the user tag
Return type:	`str`

Deprecated since version ???: Use Camel.MessageInfo.get_user_tag() on the Camel.MessageInfo directly.

do_get_permanent_flags() virtual¶

Returns:	the set of `Camel.MessageFlags` that can be permanently stored on a message between sessions. If it includes `Camel.MessageFlags.USER`, then user-defined flags will be remembered.
Return type:	`int`

do_get_quota_info_sync(cancellable) virtual¶

Parameters:	cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Returns:	a `Camel.FolderQuotaInfo`, or `None`
Return type:	`Camel.FolderQuotaInfo`

Gets a list of known quotas for folder. Free the returned Camel.FolderQuotaInfo struct with Camel.FolderQuotaInfo.free().

If quotas are not supported for folder, the function returns None and sets error to Gio.IOErrorEnum.NOT_SUPPORTED.

New in version 3.2.

do_get_summary() virtual¶

Returns:	an array of UID-s of `Camel.MessageInfo`
Return type:	[`str`]

This returns the summary information for the folder. This array should not be modified, and must be freed with Camel.Folder.free_summary().

do_get_uids() virtual¶

Returns:	a `GLib.PtrArray` of UIDs corresponding to the messages available in the folder
Return type:	[`str`]

Get the list of UIDs available in a folder. This routine is useful for finding what messages are available when the folder does not support summaries. The returned array should not be modified, and must be freed by passing it to Camel.Folder.free_uids().

do_get_uncached_uids(uids) virtual¶

Parameters:	uids ([`str`]) – the array of uids to filter down to uncached ones.
Return type:	[`str`]

Returns the known-uncached uids from a list of uids. It may return uids which are locally cached but should never filter out a uid which is not locally cached. Free the result by called Camel.Folder.free_uids(). Frees the array of UIDs returned by Camel.Folder.get_uids().

New in version 2.26.

do_has_search_capability() virtual¶

Return type:	`bool`

do_is_frozen() virtual¶

Returns:	whether or not the folder is frozen
Return type:	`bool`

do_prepare_content_refresh() virtual¶: Lets the folder know that it should refresh its content the next time from fresh. This is useful for remote accounts, to fully re-check the folder content against the server.

New in version 3.22.

do_purge_message_cache_sync(start_uid, end_uid, cancellable) virtual¶

Parameters:	start_uid (`str`) – the start message UID end_uid (`str`) – the end message UID cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Returns:	`True` on success, `False` on failure
Return type:	`bool`

Delete the local cache of all messages between these uids.

New in version 3.4.

do_refresh_info_sync(cancellable) virtual¶

Parameters:	cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Returns:	`True` on success, `False` on error
Return type:	`bool`

Synchronizes a folder’s summary with its backing store.

New in version 3.0.

do_rename(new_name) virtual¶

Parameters:	new_name (`str`) – new name for the folder

Marks folder as renamed.

This also emits the Camel.Folder ::renamed signal from an idle source on the main loop. The idle source’s priority is GLib.PRIORITY_HIGH_IDLE.

NOTE: This is an internal function used by camel stores, no locking is performed on the folder.

do_renamed(old_name) virtual¶

Parameters:	old_name (`str`) –

do_search_by_expression(expression, cancellable) virtual¶

Parameters:	expression (`str`) – a search expression cancellable (`Gio.Cancellable` or `None`) – a `Gio.Cancellable`
Returns:	a `GLib.PtrArray` of uids of matching messages. The caller must free the list and each of the elements when it is done.
Return type:	[`str`]

Searches the folder for messages matching the given search expression.

do_search_by_uids(expression, uids, cancellable) virtual¶

Parameters:	expression (`str`) – search expression uids ([`str`]) – array of uid’s to match against. cancellable (`Gio.Cancellable` or `None`) – a `Gio.Cancellable`
Returns:	a `GLib.PtrArray` of uids of matching messages. The caller must free the list and each of the elements when it is done.
Return type:	[`str`]

Search a subset of uid’s for an expression match.

do_search_free(result) virtual¶

Parameters:	result ([`str`]) – search results to free

Free the result of a search as gotten by Camel.Folder.search_by_expression() or Camel.Folder.search_by_uids().

do_set_message_flags(uid, mask, set) virtual¶

Parameters:	uid (`str`) – the UID of a message in folder mask (`int`) – a mask of `Camel.MessageFlags` bit-or values to use set (`int`) – the flags to ser, also bit-or of `Camel.MessageFlags`
Returns:	`True` if the flags were changed or `False` otherwise
Return type:	`bool`

Sets those flags specified by mask to the values specified by set on the indicated message. (This may or may not persist after the folder or store is closed. See Camel.Folder.get_permanent_flags())

E.g. to set the deleted flag and clear the draft flag, use Camel.Folder.set_message_flags (folder, uid, Camel.MessageFlags.DELETED|:obj:Camel.MessageFlags.DRAFT, Camel.MessageFlags.DELETED);

Deprecated since version ???: Use Camel.MessageInfo.set_flags() on the message info directly (when it works)

do_set_message_user_flag(uid, name, value) virtual¶

Parameters:	uid (`str`) – the UID of a message in folder name (`str`) – the name of the user flag to set value (`bool`) – the value to set it to

Deprecated since version ???: Use Camel.MessageInfo.set_user_flag() on the Camel.MessageInfo directly (when it works) Sets the user flag specified by name to the value specified by value on the indicated message. (This may or may not persist after the folder or store is closed. See Camel.Folder.get_permanent_flags())

do_set_message_user_tag(uid, name, value) virtual¶

Parameters:	uid (`str`) – the UID of a message in folder name (`str`) – the name of the user tag to set value (`str`) – the value to set it to

Deprecated since version ???: Use Camel.MessageInfo.set_user_tag() on the Camel.MessageInfo directly (when it works). Sets the user tag specified by name to the value specified by value on the indicated message. (This may or may not persist after the folder or store is closed. See Camel.Folder.get_permanent_flags())

do_sort_uids(uids) virtual¶

Parameters:	uids ([`str`]) – array of uids

Sorts the array of UIDs.

New in version 2.24.

do_synchronize_message_sync(message_uid, cancellable) virtual¶

Parameters:	message_uid (`str`) – a message UID cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Returns:	`True` on success, `False` on error
Return type:	`bool`

Ensure that a message identified by message_uid has been synchronized in folder so that calling Camel.Folder.get_message() on it later will work in offline mode.

New in version 3.0.

do_synchronize_sync(expunge, cancellable) virtual¶

Parameters:	expunge (`bool`) – whether to expunge after synchronizing cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Returns:	`True` on success, `False` on error
Return type:	`bool`

Synchronizes any changes that have been made to folder to its backing store, optionally expunging deleted messages as well.

New in version 3.0.

do_thaw() virtual¶: Thaws the folder and emits any pending folder_changed signals.

do_transfer_messages_to_sync(message_uids, destination, delete_originals, cancellable) virtual¶

Parameters:

message_uids ([str]) – message UIDs in source
destination (Camel.Folder) – the destination Camel.Folder
delete_originals (bool) – whether or not to delete the original messages
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Returns:

True on success, False on failure

transferred_uids:
	if non-`None`, the UIDs of the resulting messages in destination will be stored here, if known.

Return type:

(bool, transferred_uids: [str])

Copies or moves messages from one folder to another. If the source and destination folders have the same parent_store, this may be more efficient than using Camel.Folder.append_message_sync().

New in version 3.0.

Signal Details¶

Camel.Folder.signals.changed(folder, changes)¶

Signal Name:	`changed`
Flags:	`RUN_FIRST`
Parameters:	folder (`Camel.Folder`) – The object which received the signal changes (`Camel.FolderChangeInfo`) – the `Camel.FolderChangeInfo` with the list of changes

Camel.Folder.signals.deleted(folder)¶

Signal Name:	`deleted`
Flags:	`RUN_FIRST`
Parameters:	folder (`Camel.Folder`) – The object which received the signal

Camel.Folder.signals.renamed(folder, old_name)¶

Signal Name:	`renamed`
Flags:	`RUN_FIRST`
Parameters:	folder (`Camel.Folder`) – The object which received the signal old_name (`str`) – the previous folder name

Property Details¶

Camel.Folder.props.description¶

Name:	`description`
Type:	`str`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT`, `EXPLICIT_NOTIFY`

The folder’s description.

Camel.Folder.props.display_name¶

Name:	`display-name`
Type:	`str`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT`, `EXPLICIT_NOTIFY`

The folder’s display name.

Camel.Folder.props.full_name¶

Name:	`full-name`
Type:	`str`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT`, `EXPLICIT_NOTIFY`

The folder’s fully qualified name.

Camel.Folder.props.mark_seen¶

Name:	`mark-seen`
Type:	`Camel.ThreeState`
Default Value:	`Camel.ThreeState.INCONSISTENT`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT`, `EXPLICIT_NOTIFY`

A Camel.ThreeState persistent option of the folder, which can override global option to mark messages as seen after certain interval.

New in version 3.32.

Camel.Folder.props.mark_seen_timeout¶

Name:	`mark-seen-timeout`
Type:	`int`
Default Value:	`1500`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT`, `EXPLICIT_NOTIFY`

Timeout in milliseconds for marking messages as seen.

New in version 3.32.

Camel.Folder.props.parent_store¶

Name:	`parent-store`
Type:	`Camel.Store`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT_ONLY`

The Camel.Store to which the folder belongs.