Camel.Folder ¶

Returns:

True on success, False on error

appended_uid:: if non-None, the UID of the appended message will be returned here, if it is known

Return type:

(bool, appended_uid: str or None)

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

New in version 3.0.

append_message_sync(message, info, cancellable)¶

Parameters:

message (Camel.MimeMessage) – a Camel.MimeMessage
info (Camel.MessageInfo or None) – a Camel.MessageInfo with additional flags/etc to set on the new message, or None
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

Returns:

True on success, False on error

appended_uid:: if non-None, the UID of the appended message will be returned here, if it is known

Return type:

(bool, appended_uid: str or None)

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:

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:

Returns:

an interger

Return type:

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_display_name()¶

Returns:: full path to the self suitable for the display to a user
Return type:: str

Similar to the Camel.Folder.get_full_name(), only returning full path to the self suitable for the display to a user.

New in version 3.46.

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 or None

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:

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:

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 on error
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 on error
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:

Returns:

True on success, False on failure

Return type:

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:

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:

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:

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:

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:

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 success, 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:

Returns:

True on success, False on error

Return type:

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:

Returns:

True on success, False on error

Return type:

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:

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:

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, cancellable) virtual¶

Parameters:

message (Camel.MimeMessage) – a Camel.MimeMessage
info (Camel.MessageInfo or None) – a Camel.MessageInfo with additional flags/etc to set on the new message, or None
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Returns:

True on success, False on error

appended_uid:: if non-None, the UID of the appended message will be returned here, if it is known

Return type:

(bool, appended_uid: str or None)

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:

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:

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_full_display_name() virtual¶

Returns:: full path to the folder suitable for the display to a user
Return type:: str

Similar to the Camel.Folder.get_full_name(), only returning full path to the folder suitable for the display to a user.

New in version 3.46.

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 or None

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:

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 on error
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:

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:

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:

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:

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:

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: