Camel.Session¶

Subclasses:: None

Methods¶

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

	`add_service` (uid, protocol, type)
	`addressbook_contains_sync` (book_uid, email_address, cancellable)
	`authenticate` (service, mechanism, io_priority, cancellable, callback, *user_data)
	`authenticate_finish` (result)
	`authenticate_sync` (service, mechanism, cancellable)
	`forget_password` (service, item)
	`forward_to` (folder, message, address, io_priority, cancellable, callback, *user_data)
	`forward_to_finish` (result)
	`forward_to_sync` (folder, message, address, cancellable)
	`get_filter_driver` (type, for_folder)
	`get_junk_filter` ()
	`get_junk_headers` ()
	`get_oauth2_access_token_sync` (service, cancellable)
	`get_online` ()
	`get_password` (service, prompt, item, flags)
	`get_recipient_certificates_sync` (flags, recipients, cancellable)
	`get_user_cache_dir` ()
	`get_user_data_dir` ()
	`idle_add` (priority, function, *data)
	`list_services` ()
	`lookup_addressbook` (name)
	`ref_main_context` ()
	`ref_network_monitor` ()
	`ref_service` (uid)
	`ref_service_by_url` (url, type)
	`remove_service` (service)
	`remove_services` ()
	`set_junk_filter` (junk_filter)
	`set_junk_headers` (headers, values)
	`set_network_monitor` (network_monitor)
	`set_online` (online)
	`submit_job` (description, callback, *user_data)
	`trust_prompt` (service, certificate, errors)
	`user_alert` (service, type, message)

Virtual Methods¶

Inherited:: GObject.Object (7)

	`do_add_service` (uid, protocol, type)
	`do_addressbook_contains_sync` (book_uid, email_address, cancellable)
	`do_authenticate_sync` (service, mechanism, cancellable)
	`do_forget_password` (service, item)
	`do_forward_to_sync` (folder, message, address, cancellable)
	`do_get_filter_driver` (type, for_folder)
	`do_get_oauth2_access_token_sync` (service, cancellable)
	`do_get_password` (service, prompt, item, flags)
	`do_get_recipient_certificates_sync` (flags, recipients, cancellable)
	`do_job_finished` (cancellable, error)
	`do_job_started` (cancellable)
	`do_lookup_addressbook` (name)
	`do_remove_service` (service)
	`do_trust_prompt` (service, certificate, errors)
	`do_user_alert` (service, type, message)

Properties¶

Name	Type	Flags	Short Description
`junk-filter`	`Camel.JunkFilter`	r/w/en	Classifies messages as junk or not junk
`main-context`	`GLib.MainContext`	r	The main loop context on which to attach event sources
`network-monitor`	`Gio.NetworkMonitor`	r/w/en
`online`	`bool`	r/w/c/en	Whether the shell is online
`user-cache-dir`	`str`	r/w/c/en	User-specific base directory for mail cache
`user-data-dir`	`str`	r/w/c/en	User-specific base directory for mail data

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`job-finished`
`job-started`
`user-alert`	This purpose of this signal is to propagate a server-issued alert message from service to a user interface.

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent	`GObject.Object`	r

Class Details¶

class Camel.Session(**kwargs)¶

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

add_service(uid, protocol, type)¶

Parameters:

uid (str) – a unique identifier string
protocol (str) – the service protocol
type (Camel.ProviderType) – the service type

Raises:

GLib.Error

Returns:

a Camel.Service instance, or None on error

Return type:

Camel.Service

Instantiates a new Camel.Service for self. The uid identifies the service for future lookup. The protocol indicates which Camel.Provider holds the GObject.GType of the Camel.Service subclass to instantiate. The type explicitly designates the service as a Camel.Store or Camel.Transport.

If the given uid has already been added, the existing Camel.Service with that uid is returned regardless of whether it agrees with the given protocol and type.

If no Camel.Provider is available to handle the given protocol, or if the Camel.Provider does not specify a valid GObject.GType for type, the function sets error and returns None.

The returned Camel.Service is referenced for thread-safety and must be unreferenced with GObject.Object.unref() when finished with it.

New in version 3.2.

addressbook_contains_sync(book_uid, email_address, cancellable)¶

Parameters:

book_uid (str) – an address book UID
email_address (str) – an email address to check for
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

True, when the email_address could be found in the book_uid

Return type:

bool

Look up in an address book book_uid for an address email_address and returns whether any such contact exists.

The book_uid can be either one of the special constants Camel.SESSION_BOOK_UID_ANY or Camel.SESSION_BOOK_UID_COMPLETION, or it can be a UID of a configured address book.

The email_address can contain multiple addresses, then the function checks whether any of the given addresses is in the address book.

New in version 3.44.

authenticate(service, mechanism, io_priority, cancellable, callback, *user_data)¶

Parameters:

service (Camel.Service) – a Camel.Service
mechanism (str or None) – a SASL mechanism name, or None
io_priority (int) – the I/O priority for 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 authenticates service, which may involve repeated calls to Camel.Service.authenticate() or Camel.Service.authenticate_sync(). A Camel.Session subclass is largely responsible for implementing this, and should handle things like user prompts and secure password storage. These issues are out-of-scope for Camel.

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

New in version 3.4.

authenticate_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.Session.authenticate().

If an error occurred, or if authentication was aborted, the function sets error and returns False.

New in version 3.4.

authenticate_sync(service, mechanism, cancellable)¶

Parameters:

service (Camel.Service) – a Camel.Service
mechanism (str or None) – a SASL mechanism name, or None
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

True on success, False on failure

Return type:

bool

Authenticates service, which may involve repeated calls to Camel.Service.authenticate() or Camel.Service.authenticate_sync(). A Camel.Session subclass is largely responsible for implementing this, and should handle things like user prompts and secure password storage. These issues are out-of-scope for Camel.

If an error occurs, or if authentication is aborted, the function sets error and returns False.

New in version 3.4.

forget_password(service, item)¶

Parameters:

service (Camel.Service) – the Camel.Service rejecting the password
item (str) – an identifier, unique within this service, for the information

Raises:

GLib.Error

Returns:

True on success, False on failure

Return type:

bool

This function is used by a Camel.Service to tell the application that the authentication information it provided via Camel.Session.get_password() was rejected by the service. If the application was caching this information, it should stop, and if the service asks for it again, it should ask the user.

service and item identify the rejected authentication information, as with Camel.Session.get_password().

forward_to(folder, message, address, io_priority, cancellable, callback, *user_data)¶

Parameters:

folder (Camel.Folder) – the Camel.Folder where message is located
message (Camel.MimeMessage) – the Camel.MimeMessage to forward
address (str) – the recipient’s email address
io_priority (int) – the I/O priority for 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 forwards message in folder to the email address(s) given by address.

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

New in version 3.6.

forward_to_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.Session.forward_to().

If an error occurred, the function sets error and returns False.

New in version 3.6.

forward_to_sync(folder, message, address, cancellable)¶

Parameters:

folder (Camel.Folder) – the Camel.Folder where message is located
message (Camel.MimeMessage) – the Camel.MimeMessage to forward
address (str) – the recipient’s email address
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

True on success, False on failure

Return type:

bool

Forwards message in folder to the email address(es) given by address.

If an error occurs, the function sets error and returns False.

New in version 3.6.

get_filter_driver(type, for_folder)¶

Parameters:

type (str) – the type of filter (eg, “incoming”)
for_folder (Camel.Folder or None) – an optional Camel.Folder, for which the filter driver will run, or None

Raises:

GLib.Error

Returns:

a filter driver, loaded with applicable rules

Return type:

Camel.FilterDriver

The optional for_folder can be used to determine which filters to add and which not.

get_junk_filter()¶

Returns:: a Camel.JunkFilter, or None
Return type:: Camel.JunkFilter or None

Returns the Camel.JunkFilter instance used to classify messages as junk or not junk during filtering.

Note that Camel.JunkFilter itself is just an interface. The application must implement the interface and install a Camel.JunkFilter instance for junk filtering to take place.

New in version 3.2.

get_junk_headers()¶

Returns:: Currently used junk headers as a hash table, previously set by Camel.Session.set_junk_headers().
Return type:: {str: str}

New in version 2.22.

get_oauth2_access_token_sync(service, cancellable)¶

Parameters:

service (Camel.Service) – a Camel.Service
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

whether succeeded

out_access_token:: return location for the access token, or None
out_expires_in:: return location for the token expiry, or None

Return type:

(bool, out_access_token: str or None, out_expires_in: int)

Obtains the OAuth 2.0 access token for service along with its expiry in seconds from the current time (or 0 if unknown).

Free the returned access token with GLib.free() when no longer needed.

New in version 3.28.

get_online()¶

Returns:: whether or not self is online
Return type:: bool

get_password(service, prompt, item, flags)¶

Parameters:

service (Camel.Service) – the Camel.Service this query is being made by
prompt (str) – prompt to provide to user
item (str) – an identifier, unique within this service, for the information
flags (int) – %CAMEL_SESSION_PASSWORD_REPROMPT, the prompt should force a reprompt %CAMEL_SESSION_PASSWORD_SECRET, whether the password is secret %CAMEL_SESSION_PASSWORD_STATIC, the password is remembered externally

Raises:

GLib.Error

Returns:

the authentication information or None on error

Return type:

str

This function is used by a Camel.Service to ask the application and the user for a password or other authentication data.

service and item together uniquely identify the piece of data the caller is concerned with.

prompt is a question to ask the user (if the application doesn’t already have the answer cached). If %CAMEL_SESSION_PASSWORD_SECRET is set, the user’s input will not be echoed back.

If %CAMEL_SESSION_PASSWORD_STATIC is set, it means the password returned will be stored statically by the caller automatically, for the current session.

The authenticator should set error to Gio.IOErrorEnum.CANCELLED if the user did not provide the information. The caller must GLib.free() the information returned when it is done with it.

get_recipient_certificates_sync(flags, recipients, cancellable)¶

Parameters:

flags (int) – bit-or of Camel.RecipientCertificateFlags
recipients ([str]) – a GLib.PtrArray of recipients
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded, or better whether no fatal error happened.

out_certificates:: a GLib.SList of gathered certificates

Return type:

(bool, out_certificates: [str])

Searches for S/MIME certificates or PGP keys for the given recipients, which are returned as base64 encoded strings in out_certificates. This is used when encrypting messages. The flags influence what the out_certificates will contain. The order of items in out_certificates should match the order of items in recipients, with None data for those which could not be found.

The function should return failure only if some fatal error happened. It’s not an error when certificates for some, or all, recipients could not be found.

This method is optional and the default implementation returns True and sets the out_certificates to None. It’s the only exception when the length of recipients and out_certificates can differ. In all other cases the length of the two should match.

The out_certificates will be freed with g_slist_free_full (certificates, GLib.free); when done with it.

New in version 3.30.

get_user_cache_dir()¶

Returns:: the base directory for mail cache
Return type:: str

Returns the base directory under which to store user-specific mail cache.

New in version 3.4.

get_user_data_dir()¶

Returns:: the base directory for mail data
Return type:: str

Returns the base directory under which to store user-specific mail data.

New in version 3.2.

idle_add(priority, function, *data)¶

Parameters:

priority (int) – the priority of the idle source
function (GLib.SourceFunc) – a function to call
data (object or None) – data to pass to function

Returns:

the ID (greater than 0) of the event source

Return type:

int

Adds a function to be called whenever there are no higher priority events pending. If function returns False it is automatically removed from the list of event sources and will not be called again.

This internally creates a main loop source using GLib.idle_source_new() and attaches it to self's own Camel.Session :main-context using GLib.Source.attach().

The priority is typically in the range between GLib.PRIORITY_DEFAULT_IDLE and GLib.PRIORITY_HIGH_IDLE.

New in version 3.6.

list_services()¶

Returns:: an unsorted list of Camel.Service objects
Return type:: [Camel.Service]

Returns a list of all Camel.Service objects previously added using Camel.Session.add_service().

The services returned in the list are referenced for thread-safety. They must each be unreferenced with GObject.Object.unref() when finished with them. Free the returned list itself with g_list_free().

An easy way to free the list property in one step is as follows:

g_list_free_full (list, g_object_unref);

New in version 3.2.

lookup_addressbook(name)¶

Parameters:: name (str) – a name/address to lookup for
Returns:: whether found the name in any address book.
Return type:: bool

Looks up for the name in address books.

New in version 2.22.

ref_main_context()¶

Returns:: a GLib.MainContext
Return type:: GLib.MainContext

Returns the GLib.MainContext on which event sources for self are to be attached.

New in version 3.8.

ref_network_monitor()¶

Returns:: A referenced Gio.NetworkMonitor instance to use for network availability tests.
Return type:: Gio.NetworkMonitor

References a Gio.NetworkMonitor instance, which had been previously set by Camel.Session.set_network_monitor(). If none is set, then the default Gio.NetworkMonitor is returned, as provided by Gio.NetworkMonitor.get_default(). The returned pointer is referenced for thread safety, unref it with GObject.Object.unref() when no longer needed.

New in version 3.22.

ref_service(uid)¶

Parameters:: uid (str) – a unique identifier string
Returns:: a Camel.Service instance, or None
Return type:: Camel.Service or None

Looks up a Camel.Service by its unique identifier string. The service must have been previously added using Camel.Session.add_service().

The returned Camel.Service is referenced for thread-safety and must be unreferenced with GObject.Object.unref() when finished with it.

New in version 3.6.

ref_service_by_url(url, type)¶

Parameters:

url (Camel.URL) – a Camel.URL
type (Camel.ProviderType) – a Camel.ProviderType

Returns:

a Camel.Service instance, or None

Return type:

Camel.Service or None

Looks up a Camel.Service by trying to match its Camel.URL against the given url and then checking that the object is of the desired type. The service must have been previously added using Camel.Session.add_service().

The returned Camel.Service is referenced for thread-safety and must be unreferenced with GObject.Object.unref() when finished with it.

Note this function is significantly slower than Camel.Session.ref_service().

New in version 3.6.

remove_service(service)¶

Parameters:: service (Camel.Service) – the Camel.Service to remove

Removes a Camel.Service previously added by Camel.Session.add_service().

New in version 3.2.

remove_services()¶

Removes all Camel.Service instances added by Camel.Session.add_service().

This can be useful during application shutdown to ensure all Camel.Service instances are freed properly, especially since Camel.Session instances are prone to reference cycles.

New in version 3.2.

set_junk_filter(junk_filter)¶

Parameters:: junk_filter (Camel.JunkFilter or None) – a Camel.JunkFilter, or None

Installs the Camel.JunkFilter instance used to classify messages as junk or not junk during filtering.

Note that Camel.JunkFilter itself is just an interface. The application must implement the interface and install a Camel.JunkFilter instance for junk filtering to take place.

New in version 3.2.

set_junk_headers(headers, values)¶

Parameters:

headers ([str]) –
values ([str]) –

New in version 2.22.

set_network_monitor(network_monitor)¶

Parameters:: network_monitor (Gio.NetworkMonitor or None) – a Gio.NetworkMonitor or None

Sets a network monitor instance for the self. This can be used to override which Gio.NetworkMonitor should be used to check network availability and whether a server is reachable.

New in version 3.22.

set_online(online)¶

Parameters:: online (bool) – whether or not the session should be online

Sets the online status of self to online.

submit_job(description, callback, *user_data)¶

Parameters:

description (str) – human readable description of the job, shown to a user
callback (Camel.SessionCallback) – a Camel.SessionCallback
user_data (object or None) – user data passed to the callback

This function provides a simple mechanism for providers to initiate low-priority background jobs. Jobs can be submitted from any thread, but execution of the jobs is always as follows:

1) The Camel.Session :job-started signal is emitted from the thread in which self was created. This is typically the same thread that hosts the global default GLib.MainContext, or “main” thread.

2) The callback function is invoked from a different thread where it’s safe to call synchronous functions.

3) Once callback has returned, the #CamelSesson:job-finished signal is emitted from the same thread as Camel.Session :job-started was emitted.

4) Finally if a notify function was provided, it is invoked and passed user_data so that user_data can be freed.

New in version 3.2.

trust_prompt(service, certificate, errors)¶

Parameters:

service (Camel.Service) – a Camel.Service
certificate (Gio.TlsCertificate) – the peer’s Gio.TlsCertificate
errors (Gio.TlsCertificateFlags) – the problems with certificate

Returns:

the user’s trust level for certificate

Return type:

Camel.CertTrust

Prompts the user whether to accept certificate for service. The set of flags given in errors indicate why the certificate failed validation.

If an error occurs during prompting or if the user declines to respond, the function returns Camel.CertTrust.UNKNOWN and the certificate will be rejected.

New in version 3.8.

user_alert(service, type, message)¶

Parameters:

service (Camel.Service) – a Camel.Service
type (Camel.SessionAlertType) – a Camel.SessionAlertType
message (str) – the message for the user

Emits a #CamelSession:user_alert signal from an idle source on the main loop. The idle source’s priority is GLib.PRIORITY_LOW.

The purpose of the signal is to propagate a server-issued alert message from service to a user interface. The type hints at the nature of the alert message.

New in version 3.12.

do_add_service(uid, protocol, type) virtual¶

Parameters:

uid (str) – a unique identifier string
protocol (str) – the service protocol
type (Camel.ProviderType) – the service type

Returns:

a Camel.Service instance, or None on error

Return type:

Camel.Service

Instantiates a new Camel.Service for session. The uid identifies the service for future lookup. The protocol indicates which Camel.Provider holds the GObject.GType of the Camel.Service subclass to instantiate. The type explicitly designates the service as a Camel.Store or Camel.Transport.

If the given uid has already been added, the existing Camel.Service with that uid is returned regardless of whether it agrees with the given protocol and type.

If no Camel.Provider is available to handle the given protocol, or if the Camel.Provider does not specify a valid GObject.GType for type, the function sets error and returns None.

The returned Camel.Service is referenced for thread-safety and must be unreferenced with GObject.Object.unref() when finished with it.

New in version 3.2.

do_addressbook_contains_sync(book_uid, email_address, cancellable) virtual¶

Parameters:

book_uid (str) – an address book UID
email_address (str) – an email address to check for
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Returns:

True, when the email_address could be found in the book_uid

Return type:

bool

Look up in an address book book_uid for an address email_address and returns whether any such contact exists.

The book_uid can be either one of the special constants Camel.SESSION_BOOK_UID_ANY or Camel.SESSION_BOOK_UID_COMPLETION, or it can be a UID of a configured address book.

The email_address can contain multiple addresses, then the function checks whether any of the given addresses is in the address book.

New in version 3.44.

do_authenticate_sync(service, mechanism, cancellable) virtual¶

Parameters:

service (Camel.Service) – a Camel.Service
mechanism (str or None) – a SASL mechanism name, or None
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Returns:

True on success, False on failure

Return type:

bool

Authenticates service, which may involve repeated calls to Camel.Service.authenticate() or Camel.Service.authenticate_sync(). A Camel.Session subclass is largely responsible for implementing this, and should handle things like user prompts and secure password storage. These issues are out-of-scope for Camel.

If an error occurs, or if authentication is aborted, the function sets error and returns False.

New in version 3.4.

do_forget_password(service, item) virtual¶

Parameters:

service (Camel.Service) – the Camel.Service rejecting the password
item (str) – an identifier, unique within this service, for the information

Returns:

True on success, False on failure

Return type:

bool

This function is used by a Camel.Service to tell the application that the authentication information it provided via Camel.Session.get_password() was rejected by the service. If the application was caching this information, it should stop, and if the service asks for it again, it should ask the user.

service and item identify the rejected authentication information, as with Camel.Session.get_password().

do_forward_to_sync(folder, message, address, cancellable) virtual¶

Parameters:

folder (Camel.Folder) – the Camel.Folder where message is located
message (Camel.MimeMessage) – the Camel.MimeMessage to forward
address (str) – the recipient’s email address
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Returns:

True on success, False on failure

Return type:

bool

Forwards message in folder to the email address(es) given by address.

If an error occurs, the function sets error and returns False.

New in version 3.6.

do_get_filter_driver(type, for_folder) virtual¶

Parameters:

type (str) – the type of filter (eg, “incoming”)
for_folder (Camel.Folder or None) – an optional Camel.Folder, for which the filter driver will run, or None

Returns:

a filter driver, loaded with applicable rules

Return type:

Camel.FilterDriver

The optional for_folder can be used to determine which filters to add and which not.

do_get_oauth2_access_token_sync(service, cancellable) virtual¶

Parameters:

service (Camel.Service) – a Camel.Service
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Returns:

whether succeeded

out_access_token:: return location for the access token, or None
out_expires_in:: return location for the token expiry, or None

Return type:

(bool, out_access_token: str or None, out_expires_in: int)

Obtains the OAuth 2.0 access token for service along with its expiry in seconds from the current time (or 0 if unknown).

Free the returned access token with GLib.free() when no longer needed.

New in version 3.28.

do_get_password(service, prompt, item, flags) virtual¶

Parameters:

service (Camel.Service) – the Camel.Service this query is being made by
prompt (str) – prompt to provide to user
item (str) – an identifier, unique within this service, for the information
flags (int) – %CAMEL_SESSION_PASSWORD_REPROMPT, the prompt should force a reprompt %CAMEL_SESSION_PASSWORD_SECRET, whether the password is secret %CAMEL_SESSION_PASSWORD_STATIC, the password is remembered externally

Returns:

the authentication information or None on error

Return type:

str

This function is used by a Camel.Service to ask the application and the user for a password or other authentication data.

service and item together uniquely identify the piece of data the caller is concerned with.

prompt is a question to ask the user (if the application doesn’t already have the answer cached). If %CAMEL_SESSION_PASSWORD_SECRET is set, the user’s input will not be echoed back.

If %CAMEL_SESSION_PASSWORD_STATIC is set, it means the password returned will be stored statically by the caller automatically, for the current session.

The authenticator should set error to Gio.IOErrorEnum.CANCELLED if the user did not provide the information. The caller must GLib.free() the information returned when it is done with it.

do_get_recipient_certificates_sync(flags, recipients, cancellable) virtual¶

Parameters:

flags (int) – bit-or of Camel.RecipientCertificateFlags
recipients ([str]) – a GLib.PtrArray of recipients
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Returns:

Whether succeeded, or better whether no fatal error happened.

out_certificates:: a GLib.SList of gathered certificates

Return type:

(bool, out_certificates: [str])

Searches for S/MIME certificates or PGP keys for the given recipients, which are returned as base64 encoded strings in out_certificates. This is used when encrypting messages. The flags influence what the out_certificates will contain. The order of items in out_certificates should match the order of items in recipients, with None data for those which could not be found.

The function should return failure only if some fatal error happened. It’s not an error when certificates for some, or all, recipients could not be found.

This method is optional and the default implementation returns True and sets the out_certificates to None. It’s the only exception when the length of recipients and out_certificates can differ. In all other cases the length of the two should match.

The out_certificates will be freed with g_slist_free_full (certificates, GLib.free); when done with it.

New in version 3.30.

do_job_finished(cancellable, error) virtual¶

Parameters:

cancellable (Gio.Cancellable or None) –
error (GLib.Error) –

do_job_started(cancellable) virtual¶

Parameters:: cancellable (Gio.Cancellable or None) –

do_lookup_addressbook(name) virtual¶

Parameters:: name (str) – a name/address to lookup for
Returns:: whether found the name in any address book.
Return type:: bool

Looks up for the name in address books.

New in version 2.22.

do_remove_service(service) virtual¶

Parameters:: service (Camel.Service) – the Camel.Service to remove

Removes a Camel.Service previously added by Camel.Session.add_service().

New in version 3.2.

do_trust_prompt(service, certificate, errors) virtual¶

Parameters:

service (Camel.Service) – a Camel.Service
certificate (Gio.TlsCertificate) – the peer’s Gio.TlsCertificate
errors (Gio.TlsCertificateFlags) – the problems with certificate

Returns:

the user’s trust level for certificate

Return type:

Camel.CertTrust

Prompts the user whether to accept certificate for service. The set of flags given in errors indicate why the certificate failed validation.

If an error occurs during prompting or if the user declines to respond, the function returns Camel.CertTrust.UNKNOWN and the certificate will be rejected.

New in version 3.8.

do_user_alert(service, type, message) virtual¶

Parameters:

service (Camel.Service) – a Camel.Service
type (Camel.SessionAlertType) – a Camel.SessionAlertType
message (str) – the message for the user

Emits a #CamelSession:user_alert signal from an idle source on the main loop. The idle source’s priority is GLib.PRIORITY_LOW.

The purpose of the signal is to propagate a server-issued alert message from service to a user interface. The type hints at the nature of the alert message.

New in version 3.12.

Signal Details¶

Camel.Session.signals.job_finished(session, object, p0)¶

Signal Name:

job-finished

Flags:

RUN_LAST

Parameters:

session (Camel.Session) – The object which received the signal
object (Gio.Cancellable or None) –
p0 (GLib.Error) –

Camel.Session.signals.job_started(session, object)¶

Signal Name:

job-started

Flags:

RUN_LAST

Parameters:

session (Camel.Session) – The object which received the signal
object (Gio.Cancellable or None) –

Camel.Session.signals.user_alert(session, service, type, message)¶

Signal Name:

user-alert

Flags:

RUN_LAST

Parameters:

session (Camel.Session) – The object which received the signal
service (Camel.Service) – the Camel.Service issuing the alert
type (Camel.SessionAlertType) – the Camel.SessionAlertType
message (str) – the alert message

This purpose of this signal is to propagate a server-issued alert message from service to a user interface. The type hints at the severity of the alert message.

Property Details¶

Camel.Session.props.junk_filter¶

Name:: junk-filter
Type:: Camel.JunkFilter
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Classifies messages as junk or not junk

Camel.Session.props.main_context¶

Name:: main-context
Type:: GLib.MainContext
Default Value:: None
Flags:: READABLE

The main loop context on which to attach event sources

Camel.Session.props.network_monitor¶

Name:: network-monitor
Type:: Gio.NetworkMonitor
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Camel.Session.props.online¶

Name:: online
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, CONSTRUCT, EXPLICIT_NOTIFY

Whether the shell is online

Camel.Session.props.user_cache_dir¶

Name:: user-cache-dir
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT, EXPLICIT_NOTIFY

User-specific base directory for mail cache

Camel.Session.props.user_data_dir¶

Name:: user-data-dir
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT, EXPLICIT_NOTIFY

User-specific base directory for mail data