Camel.Service¶

Subclasses:	`Camel.Store`, `Camel.Transport`

Methods¶

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

class	`error_quark` ()
	`authenticate` (mechanism, io_priority, cancellable, callback, *user_data)
	`authenticate_finish` (result)
	`authenticate_sync` (mechanism, cancellable)
	`connect` (io_priority, cancellable, callback, *user_data)
	`connect_finish` (result)
	`connect_sync` (cancellable)
	`disconnect` (clean, io_priority, cancellable, callback, *user_data)
	`disconnect_finish` (result)
	`disconnect_sync` (clean, cancellable)
	`dup_display_name` ()
	`dup_password` ()
	`get_connection_status` ()
	`get_display_name` ()
	`get_name` (brief)
	`get_password` ()
	`get_provider` ()
	`get_uid` ()
	`get_user_cache_dir` ()
	`get_user_data_dir` ()
	`migrate_files` ()
	`new_camel_url` ()
	`query_auth_types` (io_priority, cancellable, callback, *user_data)
	`query_auth_types_finish` (result)
	`query_auth_types_sync` (cancellable)
	`queue_task` (task, task_func)
	`ref_proxy_resolver` ()
	`ref_session` ()
	`ref_settings` ()
	`set_display_name` (display_name)
	`set_password` (password)
	`set_proxy_resolver` (proxy_resolver)
	`set_settings` (settings)

Virtual Methods¶

Inherited:	Camel.Object (2), GObject.Object (7), Gio.Initable (1)

	`do_authenticate_sync` (mechanism, cancellable)
	`do_connect_sync` (cancellable)
	`do_disconnect_sync` (clean, cancellable)
	`do_get_name` (brief)
	`do_query_auth_types_sync` (cancellable)

Properties¶

Inherited:	Camel.Object (1)

Name	Type	Flags	Short Description
`connection-status`	`Camel.ServiceConnectionStatus`	r	The connection status for the service
`display-name`	`str`	r/w/c/en	The display name for the service
`password`	`str`	r/w/c/en	The password for the service
`provider`	`Camel.Provider`	r/w/co	The `Camel.Provider` for the service
`proxy-resolver`	`Gio.ProxyResolver`	r/w/en	The proxy resolver for the service
`session`	`Camel.Session`	r/w/co	A `Camel.Session` instance
`settings`	`Camel.Settings`	r/w/c/en	A `Camel.Settings` instance
`uid`	`str`	r/w/co	The unique identity of the service

Signals¶

Inherited:	GObject.Object (1)

Fields¶

Inherited:	GObject.Object (1)

Name	Type	Access	Description
parent	`Camel.Object`	r

Class Details¶

class Camel.Service(**kwargs)¶

Bases:	`Camel.Object`, `Gio.Initable`
Abstract:	Yes
Structure:	`Camel.ServiceClass`

classmethod error_quark()¶

Return type:	`int`

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

Parameters:

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

Asynchronously attempts to authenticate self using mechanism and, if necessary, self’s Camel.Service :password property. The function makes only ONE attempt at authentication and does not loop.

Generally this function should only be called from a Camel.Session subclass in order to implement its own authentication loop.

When the operation is finished, callback will be called. You can then call Camel.Service.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:	the authentication result
Return type:	`Camel.AuthenticationResult`

Finishes the operation started with Camel.Service.authenticate().

If the authentication attempt completed and the server accepted the credentials, the function returns Camel.AuthenticationResult.ACCEPTED.

If the authentication attempt completed but the server rejected the credentials, the function returns Camel.AuthenticationResult.REJECTED.

If the authentication attempt failed to complete due to a network communication issue or some other mishap, the function sets error and returns Camel.AuthenticationResult.ERROR.

New in version 3.4.

authenticate_sync(mechanism, cancellable)¶

Parameters:	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:	the authentication result
Return type:	`Camel.AuthenticationResult`

Attempts to authenticate self using mechanism and, if necessary, self’s Camel.Service :password property. The function makes only ONE attempt at authentication and does not loop.

If the authentication attempt completed and the server accepted the credentials, the function returns Camel.AuthenticationResult.ACCEPTED.

If the authentication attempt completed but the server rejected the credentials, the function returns Camel.AuthenticationResult.REJECTED.

If the authentication attempt failed to complete due to a network communication issue or some other mishap, the function sets error and returns Camel.AuthenticationResult.ERROR.

Generally this function should only be called from a Camel.Session subclass in order to implement its own authentication loop.

New in version 3.4.

connect(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 connects self to a remote server using the information in its Camel.Service :settings instance.

If a connect operation is already in progress when this function is called, its results will be reflected in this connect operation.

If any disconnect operations are in progress when this function is called, they will be cancelled.

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

New in version 3.6.

connect_finish(result)¶

Parameters:	result (`Gio.AsyncResult`) – a `Gio.AsyncResult`
Raises:	`GLib.Error`
Returns:	`True` if the connection was made or `False` otherwise
Return type:	`bool`

Finishes the operation started with Camel.Service.connect().

New in version 3.6.

connect_sync(cancellable)¶

Parameters:	cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Raises:	`GLib.Error`
Returns:	`True` if the connection is made or `False` otherwise
Return type:	`bool`

Connects self to a remote server using the information in its Camel.Service :settings instance.

If a connect operation is already in progress when this function is called, its results will be reflected in this connect operation.

New in version 3.6.

disconnect(clean, io_priority, cancellable, callback, *user_data)¶

Parameters:

clean (bool) – whether or not to try to disconnect cleanly
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

If a disconnect operation is already in progress when this function is called, its results will be reflected in this disconnect operation.

If any connect operations are in progress when this function is called, they will be cancelled.

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

New in version 3.6.

disconnect_finish(result)¶

Parameters:	result (`Gio.AsyncResult`) – a `Gio.AsyncResult`
Raises:	`GLib.Error`
Returns:	`True` if the connection was severed or `False` otherwise
Return type:	`bool`

Finishes the operation started with Camel.Service.disconnect().

New in version 3.6.

disconnect_sync(clean, cancellable)¶

Parameters:	clean (`bool`) – whether or not to try to disconnect cleanly cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Raises:	`GLib.Error`
Returns:	`True` if the connection was severed or `False` otherwise
Return type:	`bool`

Disconnect from the service. If clean is False, it should not try to do any synchronizing or other cleanup of the connection.

If a disconnect operation is already in progress when this function is called, its results will be reflected in this disconnect operation.

If any connect operations are in progress when this function is called, they will be cancelled.

New in version 3.6.

dup_display_name()¶

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

Thread-safe variation of Camel.Service.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.12.

dup_password()¶

Returns:	a newly-allocated copy of `Camel.Service` `:password`
Return type:	`str`

Thread-safe variation of Camel.Service.get_password(). 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.12.

get_connection_status()¶

Returns:	the connection status
Return type:	`Camel.ServiceConnectionStatus`

Returns the connection status for self.

New in version 3.2.

get_display_name()¶

Returns:	the display name for self, or `None`
Return type:	`str`

Returns the display name for self, or None if self has not been given a display name. The display name is intended for use in a user interface and should generally be given a user-defined name.

Compare this with Camel.Service.get_name(), which returns a built-in description of the type of service (IMAP, SMTP, etc.).

New in version 3.2.

get_name(brief)¶

Parameters:	brief (`bool`) – whether or not to use a briefer form
Returns:	a description of the service which the caller must free
Return type:	`str`

This gets the name of the service in a “friendly” (suitable for humans) form. If brief is True, this should be a brief description such as for use in the folder tree. If brief is False, it should be a more complete and mostly unambiguous description.

get_password()¶

Returns:	the password for self
Return type:	`str`

Returns the password for self. Some SASL mechanisms use this when attempting to authenticate.

New in version 3.4.

get_provider()¶

Returns:	the `Camel.Provider`
Return type:	`Camel.Provider`

Gets the Camel.Provider associated with the service.

get_uid()¶

Returns:	the UID string
Return type:	`str`

Gets the unique identifier string associated with the service.

New in version 3.2.

get_user_cache_dir()¶

Returns:	the base cache directory for self
Return type:	`str`

Returns the base directory under which to store cache data for self. The directory is formed by appending the directory returned by Camel.Session.get_user_cache_dir() with the service’s Camel.Service :uid value.

New in version 3.4.

get_user_data_dir()¶

Returns:	the base directory for self
Return type:	`str`

Returns the base directory under which to store user-specific data for self. The directory is formed by appending the directory returned by Camel.Session.get_user_data_dir() with the service’s Camel.Service :uid value.

New in version 3.2.

migrate_files()¶: Performs any necessary file migrations for self. This should be called after installing or configuring the self’s Camel.Settings, since it requires building a URL string for self.

New in version 3.4.

new_camel_url()¶

Returns:	a new `Camel.URL`
Return type:	`Camel.URL`

Returns a new Camel.URL representing self. Free the returned Camel.URL with Camel.URL.free().

New in version 3.2.

query_auth_types(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 obtains a list of authentication types supported by self.

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

New in version 3.2.

query_auth_types_finish(result)¶

Parameters:	result (`Gio.AsyncResult`) – a `Gio.AsyncResult`
Raises:	`GLib.Error`
Returns:	a list of `Camel.ServiceAuthType` structs
Return type:	[`Camel.ServiceAuthType`]

Finishes the operation started with Camel.Service.query_auth_types(). Free the returned list with g_list_free().

New in version 3.2.

query_auth_types_sync(cancellable)¶

Parameters:	cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Raises:	`GLib.Error`
Returns:	a list of `Camel.ServiceAuthType` structs
Return type:	[`Camel.ServiceAuthType`]

Obtains a list of authentication types supported by self. Free the returned list with g_list_free().

queue_task(task, task_func)¶

Parameters:	task (`Gio.Task`) – a `Gio.Task` task_func (`Gio.TaskThreadFunc`) – function to call when task is dispatched

Adds task to a queue of waiting tasks with the same source object. Queued tasks execute one at a time in the order they were added. When task reaches the front of the queue, it will be dispatched by invoking task_func in a separate thread. If task is cancelled while queued, it will complete immediately with an appropriate error.

This is primarily intended for use by Camel.Store, Camel.Transport and Camel.Folder to achieve ordered invocation of synchronous class methods.

New in version 3.12.

ref_proxy_resolver()¶

Returns:	a `Gio.ProxyResolver`, or `None`
Return type:	`Gio.ProxyResolver`

Returns the Gio.ProxyResolver for self. If an application needs to override this, it should do so prior to calling functions on self that may require a network connection.

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

New in version 3.12.

ref_session()¶

Returns:	the `Camel.Session`
Return type:	`Camel.Session`

Returns the Camel.Session associated with the service.

The returned Camel.Session is referenced for thread-safety. Unreference the Camel.Session with GObject.Object.unref() when finished with it.

New in version 3.8.

ref_settings()¶

Returns:	the `Camel.Settings`
Return type:	`Camel.Settings`

Returns the Camel.Settings instance associated with the service.

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

New in version 3.6.

set_display_name(display_name)¶

Parameters:	display_name (`str`) – a valid UTF-8 string, or `None`

Assigns a UTF-8 display name to self. The display name is intended for use in a user interface and should generally be given a user-defined name.

Compare this with Camel.Service.get_name(), which returns a built-in description of the type of service (IMAP, SMTP, etc.).

New in version 3.2.

set_password(password)¶

Parameters:	password (`str`) – the password for self

Sets the password for self. Use this function to cache the password in memory after obtaining it through Camel.Session.get_password(). Some SASL mechanisms use this when attempting to authenticate.

New in version 3.4.

set_proxy_resolver(proxy_resolver)¶

Parameters:	proxy_resolver (`Gio.ProxyResolver`) – a `Gio.ProxyResolver`, or `None` for the default

Sets the Gio.ProxyResolver for self. If an application needs to override this, it should do so prior to calling functions on self that may require a network connection.

New in version 3.12.

set_settings(settings)¶

Parameters:	settings (`Camel.Settings`) – an instance derviced from `Camel.Settings`, or `None`

Associates a new Camel.Settings instance with the service. The settings instance must match the settings type defined in Camel.ServiceClass. If settings is None, a new Camel.Settings instance of the appropriate type is created with all properties set to defaults.

New in version 3.2.

do_authenticate_sync(mechanism, cancellable) virtual¶

Parameters:	mechanism (`str` or `None`) – a SASL mechanism name, or `None` cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Returns:	the authentication result
Return type:	`Camel.AuthenticationResult`

Attempts to authenticate service using mechanism and, if necessary, service’s Camel.Service :password property. The function makes only ONE attempt at authentication and does not loop.

If the authentication attempt completed and the server accepted the credentials, the function returns Camel.AuthenticationResult.ACCEPTED.

If the authentication attempt completed but the server rejected the credentials, the function returns Camel.AuthenticationResult.REJECTED.

If the authentication attempt failed to complete due to a network communication issue or some other mishap, the function sets error and returns Camel.AuthenticationResult.ERROR.

Generally this function should only be called from a Camel.Session subclass in order to implement its own authentication loop.

New in version 3.4.

do_connect_sync(cancellable) virtual¶

Parameters:	cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Returns:	`True` if the connection is made or `False` otherwise
Return type:	`bool`

Connects service to a remote server using the information in its Camel.Service :settings instance.

If a connect operation is already in progress when this function is called, its results will be reflected in this connect operation.

New in version 3.6.

do_disconnect_sync(clean, cancellable) virtual¶

Parameters:	clean (`bool`) – whether or not to try to disconnect cleanly cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Returns:	`True` if the connection was severed or `False` otherwise
Return type:	`bool`

Disconnect from the service. If clean is False, it should not try to do any synchronizing or other cleanup of the connection.

If a disconnect operation is already in progress when this function is called, its results will be reflected in this disconnect operation.

If any connect operations are in progress when this function is called, they will be cancelled.

New in version 3.6.

do_get_name(brief) virtual¶

Parameters:	brief (`bool`) – whether or not to use a briefer form
Returns:	a description of the service which the caller must free
Return type:	`str`

This gets the name of the service in a “friendly” (suitable for humans) form. If brief is True, this should be a brief description such as for use in the folder tree. If brief is False, it should be a more complete and mostly unambiguous description.

do_query_auth_types_sync(cancellable) virtual¶

Parameters:	cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Returns:	a list of `Camel.ServiceAuthType` structs
Return type:	[`Camel.ServiceAuthType`]

Obtains a list of authentication types supported by service. Free the returned list with g_list_free().

Property Details¶

Camel.Service.props.connection_status¶

Name:	`connection-status`
Type:	`Camel.ServiceConnectionStatus`
Default Value:	`Camel.ServiceConnectionStatus.DISCONNECTED`
Flags:	`READABLE`

The connection status for the service

Camel.Service.props.display_name¶

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

The display name for the service

Camel.Service.props.password¶

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

The password for the service

Camel.Service.props.provider¶

Name:	`provider`
Type:	`Camel.Provider`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT_ONLY`

The Camel.Provider for the service

Camel.Service.props.proxy_resolver¶

Name:	`proxy-resolver`
Type:	`Gio.ProxyResolver`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`, `EXPLICIT_NOTIFY`

The proxy resolver for the service

Camel.Service.props.session¶

Name:	`session`
Type:	`Camel.Session`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT_ONLY`

A Camel.Session instance

Camel.Service.props.settings¶

Name:	`settings`
Type:	`Camel.Settings`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT`, `EXPLICIT_NOTIFY`

A Camel.Settings instance

Camel.Service.props.uid¶

Name:	`uid`
Type:	`str`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT_ONLY`

The unique identity of the service