Class

CamelService

Description [src]

abstract class Camel.Service : GObject.Object
  implements Gio.Initable {
  CamelServicePrivate* priv
}

Base class for mail access and sending services.

CamelService is an abstract base class that is the common parent of CamelStore (mail storage and retrieval) and CamelTransport (mail sending). It defines the common operations associated with a configured mail service.

Service instances are always created and managed by CamelSession via camel_session_get_service(). The session uses the GType stored in the CamelProvider descriptor to instantiate the correct subclass.

CamelService manages the connection lifecycle: - camel_service_connect() establishes a connection to the remote resource. - camel_service_disconnect() tears it down. - Connection and authentication settings are conveyed via a CamelURL (the URI passed when the service was first requested).

Authentication is handled asynchronously through the session’s camel_session_authenticate() mechanism, which can prompt the user for credentials as needed.

The connection state is exposed as a CamelServiceConnectionStatus and signals are emitted when it changes.

Hierarchy

Ancestors

GObject

Descendants

Implements

GInitable

Instance methods

camel_service_authenticate

Asynchronously attempts to authenticate service using mechanism and, if necessary, service‘s CamelService:password property. The function makes only ONE attempt at authentication and does not loop.

since: 3.4

camel_service_authenticate_finish

Finishes the operation started with camel_service_authenticate().

since: 3.4

camel_service_authenticate_sync

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

since: 3.4

camel_service_connect

Asynchronously connects service to a remote server using the information in its CamelService:settings instance.

since: 3.6

camel_service_connect_finish

Finishes the operation started with camel_service_connect().

since: 3.6

camel_service_connect_sync

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

since: 3.6

camel_service_disconnect

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

since: 3.6

camel_service_disconnect_finish

Finishes the operation started with camel_service_disconnect().

since: 3.6

camel_service_disconnect_sync

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

since: 3.6

camel_service_dup_display_name

Thread-safe variation of camel_service_get_display_name(). Use this function when accessing service from multiple threads.

since: 3.12

camel_service_dup_password

Thread-safe variation of camel_service_get_password(). Use this function when accessing service from multiple threads.

since: 3.12

camel_service_get_connection_status

Returns the connection status for service.

since: 3.2

camel_service_get_display_name

Returns the display name for service, or NULL if service 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.

since: 3.2

camel_service_get_name

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.

camel_service_get_password

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

since: 3.4

camel_service_get_provider

Gets the CamelProvider associated with the service.

camel_service_get_uid

Gets the unique identifier string associated with the service.

since: 3.2

camel_service_get_user_cache_dir

Returns the base directory under which to store cache data for service. The directory is formed by appending the directory returned by camel_session_get_user_cache_dir() with the service’s CamelService:uid value.

since: 3.4

camel_service_get_user_data_dir

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

since: 3.2

camel_service_query_auth_types

Asynchronously obtains a list of authentication types supported by service.

since: 3.2

camel_service_query_auth_types_finish

Finishes the operation started with camel_service_query_auth_types(). Free the returned list with g_list_free().

since: 3.2

camel_service_query_auth_types_sync

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

camel_service_queue_task

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.

since: 3.12

camel_service_ref_proxy_resolver

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

since: 3.12

camel_service_ref_session

Returns the CamelSession associated with the service.

since: 3.8

camel_service_ref_settings

Returns the CamelSettings instance associated with the service.

since: 3.6

camel_service_set_display_name

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

since: 3.2

camel_service_set_password

Sets the password for service. 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.

since: 3.4

camel_service_set_proxy_resolver

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

since: 3.12

camel_service_set_settings

Associates a new CamelSettings instance with the service. The settings instance must match the settings type defined in CamelServiceClass. If settings is NULL, a new CamelSettings instance of the appropriate type is created with all properties set to defaults.

since: 3.2

Methods inherited from GObject (43)

Please see GObject for a full list of methods.

Methods inherited from GInitable (1)

g_initable_init

Initializes the object implementing the interface.

Properties

Camel.Service:connection-status

The connection status for the service.

Camel.Service:display-name

The display name for the service.

Camel.Service:password

The password for the service.

Camel.Service:provider

The CamelProvider for the service.

Camel.Service:proxy-resolver

The proxy resolver for the service.

Camel.Service:session

A CamelSession instance.

Camel.Service:settings

A CamelSettings instance.

Camel.Service:uid

The unique identity of the service.

Camel.Service:with-proxy-resolver

Private property, to not create GProxyResolver in the tests.

Signals

Signals inherited from GObject (1)

GObject::notify

The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

Class structure

struct CamelServiceClass {
  GObjectClass parent_class;
  GType settings_type;
  gchar* (* get_name) (
    CamelService* service,
    gboolean brief
  );
  gboolean (* connect_sync) (
    CamelService* service,
    GCancellable* cancellable,
    GError** error
  );
  gboolean (* disconnect_sync) (
    CamelService* service,
    gboolean clean,
    GCancellable* cancellable,
    GError** error
  );
  CamelAuthenticationResult (* authenticate_sync) (
    CamelService* service,
    const gchar* mechanism,
    GCancellable* cancellable,
    GError** error
  );
  GList* (* query_auth_types_sync) (
    CamelService* service,
    GCancellable* cancellable,
    GError** error
  );
  gpointer reserved;
  
}

No description available.

Class members

parent_class: GObjectClass: No description available.
settings_type: GType: No description available.
get_name: gchar* (* get_name) ( CamelService* service, gboolean brief ): No description available.
connect_sync: gboolean (* connect_sync) ( CamelService* service, GCancellable* cancellable, GError** error ): No description available.
disconnect_sync: gboolean (* disconnect_sync) ( CamelService* service, gboolean clean, GCancellable* cancellable, GError** error ): No description available.
authenticate_sync: CamelAuthenticationResult (* authenticate_sync) ( CamelService* service, const gchar* mechanism, GCancellable* cancellable, GError** error ): No description available.
query_auth_types_sync: GList* (* query_auth_types_sync) ( CamelService* service, GCancellable* cancellable, GError** error ): No description available.
reserved: gpointer: No description available.

Virtual methods

Camel.ServiceClass.authenticate_sync

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

since: 3.4

Camel.ServiceClass.connect_sync

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

since: 3.6

Camel.ServiceClass.disconnect_sync

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

since: 3.6

Camel.ServiceClass.get_name

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.

Camel.ServiceClass.query_auth_types_sync

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