Camel.FolderSummary¶

Subclasses:: Camel.VeeSummary

Methods¶

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

class	`free_array` (array)
class	`new` (folder)
	`add` (info, force_keep_uid)
	`check_uid` (uid)
	`clear` ()
	`count` ()
	`get` (uid)
	`get_array` ()
	`get_changed` ()
	`get_deleted_count` ()
	`get_flags` ()
	`get_folder` ()
	`get_hash` ()
	`get_index` ()
	`get_info_flags` (uid)
	`get_junk_count` ()
	`get_junk_not_deleted_count` ()
	`get_next_uid` ()
	`get_saved_count` ()
	`get_timestamp` ()
	`get_unread_count` ()
	`get_version` ()
	`get_visible_count` ()
	`header_load` (store, folder_name)
	`header_save` ()
	`info_new_from_headers` (headers)
	`info_new_from_message` (message)
	`info_new_from_parser` (parser)
	`load` ()
	`lock` ()
	`next_uid` ()
	`next_uid_string` ()
	`peek_loaded` (uid)
	`prepare_fetch_all` ()
	`remove` (info)
	`remove_uid` (uid)
	`remove_uids` (uids)
	`replace_flags` (info)
	`save` ()
	`set_flags` (flags)
	`set_index` (index)
	`set_next_uid` (uid)
	`set_timestamp` (timestamp)
	`set_version` (version)
	`touch` ()
	`unlock` ()

Virtual Methods¶

Inherited:: GObject.Object (7)

	`do_message_info_from_uid` (uid)
	`do_message_info_new_from_headers` (headers)
	`do_message_info_new_from_message` (message)
	`do_message_info_new_from_parser` (parser)
	`do_next_uid_string` ()
	`do_prepare_fetch_all` ()
	`do_summary_header_load` (fir)
	`do_summary_header_save` ()

Properties¶

Name	Type	Flags	Short Description
`deleted-count`	`int`	r	How many deleted infos is saved in a summary
`folder`	`Camel.Folder`	r/w/co	The folder to which the folder summary belongs
`junk-count`	`int`	r	How many junk infos is saved in a summary
`junk-not-deleted-count`	`int`	r	How many junk and not deleted infos is saved in a summary
`saved-count`	`int`	r	How many infos is savef in a summary
`unread-count`	`int`	r	How many unread infos is saved in a summary
`visible-count`	`int`	r	How many visible (not deleted and not junk) infos is saved in a summary

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`changed`

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent	`GObject.Object`	r

Class Details¶

class Camel.FolderSummary(**kwargs)¶

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

classmethod free_array(array)¶

Parameters:: array ([str]) – a GLib.PtrArray returned from Camel.FolderSummary.get_array()

Free’s array and its elements returned from Camel.FolderSummary.get_array().

New in version 3.4.

classmethod new(folder)¶

Parameters:: folder (Camel.Folder) – parent Camel.Folder object
Returns:: a new Camel.FolderSummary object
Return type:: Camel.FolderSummary

Create a new Camel.FolderSummary object.

add(info, force_keep_uid)¶

Parameters:

info (Camel.MessageInfo) – a Camel.MessageInfo
force_keep_uid (bool) – whether to keep set UID of the info

Adds a new info record to the summary. If the force_keep_uid is False, then a new uid is automatically re-assigned by calling Camel.FolderSummary.next_uid_string(). It’s an error to use force_keep_uid when the info has none set.

The self adds its own reference to info, if needed, and any previously loaded info is replaced with the new one.

check_uid(uid)¶

Parameters:: uid (str) – a uid
Returns:: if the uid is present in the summary or not (True or False)
Return type:: bool

Check if the uid is valid. This isn’t very efficient, so it shouldn’t be called iteratively.

New in version 2.24.

clear()¶

Raises:: GLib.Error
Returns:: whether succeeded
Return type:: bool

Empty the summary contents.

count()¶

Returns:: the number of items in the summary
Return type:: int

Get the number of summary items stored in this summary.

get(uid)¶

Parameters:

uid (str) – a uid

Returns:

the summary item, or None if the uid uid is not available

See Camel.FolderSummary.get_info_flags().

Return type:

Camel.MessageInfo or None

Retrieve a summary item by uid.

A referenced to the summary item is returned, which may be ref’d or free’d as appropriate.

New in version 3.4.

get_array()¶

Returns:: a GLib.PtrArray of uids
Return type:: [str]

Obtain a copy of the summary array. This is done atomically, so cannot contain empty entries.

Free with Camel.FolderSummary.free_array()

New in version 3.4.

get_changed()¶

Returns:: a GLib.PtrArray with changed UID-s. Free it with Camel.FolderSummary.free_array() when no longer needed.
Return type:: [str]

Returns an array of changed UID-s. A UID is considered changed when its corresponding CamelMesageInfo is ‘dirty’ or when it has set the Camel.MessageFlags.FOLDER_FLAGGED flag.

New in version 2.24.

get_deleted_count()¶

Returns:: Count of deleted infos.
Return type:: int

New in version 3.4.

get_flags()¶

Returns:: flags of the self, a bit-or of Camel.FolderSummaryFlags
Return type:: int

New in version 3.24.

get_folder()¶

Returns:: a Camel.Folder to which the summary if associated.
Return type:: object or None

New in version 3.4.

get_hash()¶

Return type:: {str: int}

Returns hash of current stored ‘uids’ in summary, where key is ‘uid’ from the string pool, and value is 1. The returned pointer should be freed with GLib.HashTable.destroy().

Note: When searching for values always use uids from the string pool.

New in version 3.6.

get_index()¶

Returns:: a Camel.Index used to index body content.
Return type:: Camel.Index or None

New in version 3.4.

get_info_flags(uid)¶

Parameters:: uid (str) – a uid
Returns:: the flags currently stored for message info with UID uid, or (~0) on error
Return type:: int

Retrieve Camel.MessageInfo ::flags for a message info with UID uid. This is much quicker than Camel.FolderSummary.get(), because it doesn’t require reading the message info from a disk.

New in version 3.12.

get_junk_count()¶

Returns:: Count of junk infos.
Return type:: int

New in version 3.4.

get_junk_not_deleted_count()¶

Returns:: Count of junk and not deleted infos.
Return type:: int

New in version 3.4.

get_next_uid()¶

Returns:: Next uid currently awaiting for assignment. The difference from Camel.FolderSummary.next_uid() is that this function returns actual value and doesn’t increment it before returning.
Return type:: int

New in version 3.4.

get_saved_count()¶

Returns:: Count of saved infos.
Return type:: int

New in version 3.4.

get_timestamp()¶

Returns:: timestamp of the self, as set by the descendants
Return type:: int

New in version 3.24.

get_unread_count()¶

Returns:: Count of unread infos.
Return type:: int

New in version 3.4.

get_version()¶

Returns:: version of the self
Return type:: int

New in version 3.24.

get_visible_count()¶

Returns:: Count of visible (not junk and not deleted) infos.
Return type:: int

New in version 3.4.

header_load(store, folder_name)¶

Parameters:

store (object or None) – a Camel.Store
folder_name (str) – a folder name corresponding to self

Raises:

GLib.Error

Returns:

whether succeeded

Return type:

bool

Loads a summary header for the self, which corresponds to folder_name provided by store.

New in version 3.24.

header_save()¶

Raises:: GLib.Error
Returns:: whether succeeded
Return type:: bool

Saves summary header information into the disk. The function does nothing, if the summary doesn’t support save to disk.

New in version 3.24.

info_new_from_headers(headers)¶

Parameters:: headers (Camel.NameValueArray) – rfc822 headers as Camel.NameValueArray
Returns:: a newly created Camel.MessageInfo. Unref it with GObject.Object.unref(), when done with it.
Return type:: Camel.MessageInfo

Create a new info record from a header.

New in version 3.24.

info_new_from_message(message)¶

Parameters:: message (Camel.MimeMessage) – a Camel.MimeMessage object
Returns:: a newly created Camel.MessageInfo. Unref it with GObject.Object.unref(), when done with it.
Return type:: Camel.MessageInfo

Create a summary item from a message.

info_new_from_parser(parser)¶

Parameters:: parser (Camel.MimeParser) – a Camel.MimeParser object
Returns:: a newly created Camel.MessageInfo. Unref it with GObject.Object.unref(), when done with it.
Return type:: Camel.MessageInfo

Create a new info record from a parser. If the parser cannot determine a uid, then none will be assigned.

If indexing is enabled, and the parser cannot determine a new uid, then one is automatically assigned.

If indexing is enabled, then the content will be indexed based on this new uid. In this case, the message info MUST be added using :add().

Once complete, the parser will be positioned at the end of the message.

load()¶

Raises:: GLib.Error
Returns:: whether succeeded
Return type:: bool

Loads the summary from the disk. It also saves any pending changes first.

New in version 3.24.

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

New in version 2.32.

next_uid()¶

Returns:: the next unique uid value
Return type:: int

Generate a new unique uid value as an integer. This may be used to create a unique sequence of numbers.

next_uid_string()¶

Returns:: the next uid as an unsigned integer string. This string must be freed by the caller.
Return type:: str

Retrieve the next uid, but as a formatted string.

peek_loaded(uid)¶

Parameters:: uid (str) – a message UID to look for
Returns:: a Camel.MessageInfo for the given uid, if it’s currently loaded in memory, or None otherwise. Unref the non-None info with GObject.Object.unref() when done with it.
Return type:: Camel.MessageInfo or None

New in version 2.26.

prepare_fetch_all()¶

Raises:: GLib.Error

Loads all infos into memory, if they are not yet and ensures they will not be freed in next couple minutes. Call this function before any mass operation or when all message infos will be needed, for better performance.

New in version 2.32.

remove(info)¶

Parameters:: info (Camel.MessageInfo) – a Camel.MessageInfo
Returns:: Whether the info was found and removed from the self.
Return type:: bool

Remove a specific info record from the summary.

remove_uid(uid)¶

Parameters:: uid (str) – a uid
Returns:: Whether the uid was found and removed from the self.
Return type:: bool

Remove a specific info record from the summary, by uid.

remove_uids(uids)¶

Parameters:: uids ([str]) – a GLib.List of uids
Returns:: Whether the uid was found and removed from the self.
Return type:: bool

Remove a specific info record from the summary, by uid.

New in version 3.6.

replace_flags(info)¶

Parameters:: info (Camel.MessageInfo) – a Camel.MessageInfo
Returns:: Whether any count changed
Return type:: bool

Updates internal counts based on the flags in info.

New in version 3.6.

save()¶

Raises:: GLib.Error
Returns:: whether succeeded
Return type:: bool

Saves the content of the self to disk. It does nothing, when the summary is not changed or when it doesn’t support permanent save.

New in version 3.24.

set_flags(flags)¶

Parameters:: flags (int) – flags to set

Sets flags of the self, a bit-or of Camel.FolderSummaryFlags.

New in version 3.24.

set_index(index)¶

Parameters:: index (Camel.Index or None) – a Camel.Index

Set the index used to index body content. If the index is None, or not set (the default), no indexing of body content will take place.

set_next_uid(uid)¶

Parameters:: uid (int) – The next minimum uid to assign. To avoid clashing uid’s, set this to the uid of a given messages + 1.

Set the next minimum uid available. This can be used to ensure new uid’s do not clash with existing uid’s.

set_timestamp(timestamp)¶

Parameters:: timestamp (int) – a timestamp to set

Sets timestamp of the self, provided by the descendants. This doesn’t change the ‘dirty’ flag of the self.

New in version 3.24.

set_version(version)¶

Parameters:: version (int) – version to set

Sets version of the self.

New in version 3.24.

touch()¶: Mark the summary as changed, so that a save will force it to be written back to disk.

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

New in version 2.32.

do_message_info_from_uid(uid) virtual¶

Parameters:

uid (str) – a uid

Returns:

the summary item, or None if the uid uid is not available

See Camel.FolderSummary.get_info_flags().

Return type:

Camel.MessageInfo or None

Retrieve a summary item by uid.

A referenced to the summary item is returned, which may be ref’d or free’d as appropriate.

New in version 3.4.

do_message_info_new_from_headers(headers) virtual¶

Parameters:: headers (Camel.NameValueArray) – rfc822 headers as Camel.NameValueArray
Returns:: a newly created Camel.MessageInfo. Unref it with GObject.Object.unref(), when done with it.
Return type:: Camel.MessageInfo

Create a new info record from a header.

New in version 3.24.

do_message_info_new_from_message(message) virtual¶

Parameters:: message (Camel.MimeMessage) – a Camel.MimeMessage object
Returns:: a newly created Camel.MessageInfo. Unref it with GObject.Object.unref(), when done with it.
Return type:: Camel.MessageInfo

Create a summary item from a message.

do_message_info_new_from_parser(parser) virtual¶

Parameters:: parser (Camel.MimeParser) – a Camel.MimeParser object
Returns:: a newly created Camel.MessageInfo. Unref it with GObject.Object.unref(), when done with it.
Return type:: Camel.MessageInfo

Create a new info record from a parser. If the parser cannot determine a uid, then none will be assigned.

If indexing is enabled, and the parser cannot determine a new uid, then one is automatically assigned.

If indexing is enabled, then the content will be indexed based on this new uid. In this case, the message info MUST be added using :add().

Once complete, the parser will be positioned at the end of the message.

do_next_uid_string() virtual¶

Returns:: the next uid as an unsigned integer string. This string must be freed by the caller.
Return type:: str

Retrieve the next uid, but as a formatted string.

do_prepare_fetch_all() virtual¶

do_summary_header_load(fir) virtual¶

Parameters:: fir (object or None) –
Return type:: bool

do_summary_header_save() virtual¶

Return type:: object or None

Signal Details¶

Camel.FolderSummary.signals.changed(folder_summary)¶

Signal Name:: changed
Flags:: RUN_FIRST
Parameters:: folder_summary (Camel.FolderSummary) – The object which received the signal

Property Details¶

Camel.FolderSummary.props.deleted_count¶

Name:: deleted-count
Type:: int
Default Value:: 0
Flags:: READABLE

How many deleted infos is saved in a summary.

Camel.FolderSummary.props.folder¶

Name:: folder
Type:: Camel.Folder
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The Camel.Folder to which the folder summary belongs.

Camel.FolderSummary.props.junk_count¶

Name:: junk-count
Type:: int
Default Value:: 0
Flags:: READABLE

How many junk infos is saved in a summary.

Camel.FolderSummary.props.junk_not_deleted_count¶

Name:: junk-not-deleted-count
Type:: int
Default Value:: 0
Flags:: READABLE

How many junk and not deleted infos is saved in a summary.

Camel.FolderSummary.props.saved_count¶

Name:: saved-count
Type:: int
Default Value:: 0
Flags:: READABLE

How many infos is saved in a summary.

Camel.FolderSummary.props.unread_count¶

Name:: unread-count
Type:: int
Default Value:: 0
Flags:: READABLE

How many unread infos is saved in a summary.

Camel.FolderSummary.props.visible_count¶

Name:: visible-count
Type:: int
Default Value:: 0
Flags:: READABLE

How many visible (not deleted and not junk) infos is saved in a summary.