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`

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`) – 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.