Camel.Session
Description: Reference for Camel.Session

### Class

# CamelSession

#### Description

    class Camel.Session : GObject.Object
    {
      CamelSessionPrivate* priv
    }

No description available.

#### Hierarchy

#### Ancestors

- GObject

#### Instance methods

###### camel_session_add_service

Instantiates a new `CamelService` for `session`. The `uid` identifies the service for future lookup. The `protocol` indicates which `CamelProvider` holds the `GType` of the `CamelService` subclass to instantiate. The `type` explicitly designates the service as a `CamelStore` or `CamelTransport`.

since: 3.2

###### camel_session_addressbook_contains_sync

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

since: 3.44

###### camel_session_authenticate

Asynchronously authenticates `service`, which may involve repeated calls to `camel_service_authenticate()` or camel_service_authenticate_sync(). A `CamelSession` 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.

since: 3.4

###### camel_session_authenticate_finish

Finishes the operation started with camel_session_authenticate().

since: 3.4

###### camel_session_authenticate_sync

Authenticates `service`, which may involve repeated calls to `camel_service_authenticate()` or camel_service_authenticate_sync(). A `CamelSession` 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.

since: 3.4

###### camel_session_forget_password

This function is used by a `CamelService` 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.

###### camel_session_forward_to

Asynchronously forwards `message` in `folder` to the email address(s) given by `address`.

since: 3.6

###### camel_session_forward_to_finish

Finishes the operation started with camel_session_forward_to().

since: 3.6

###### camel_session_forward_to_sync

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

since: 3.6

###### camel_session_get_filter_driver

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

###### camel_session_get_junk_filter

Returns the `CamelJunkFilter` instance used to classify messages as junk or not junk during filtering.

since: 3.2

###### camel_session_get_junk_headers

No description available.

since: 2.22

###### camel_session_get_oauth2_access_token_sync

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

since: 3.28

###### camel_session_get_online

No description available.

###### camel_session_get_password

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

###### camel_session_get_recipient_certificates_sync

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 `NULL` data for those which could not be found.

since: 3.30

###### camel_session_get_user_cache_dir

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

since: 3.4

###### camel_session_get_user_data_dir

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

since: 3.2

###### camel_session_idle_add

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.

since: 3.6

###### camel_session_list_services

Returns a list of all `CamelService` objects previously added using camel_session_add_service().

since: 3.2

###### camel_session_lookup_addressbook

Looks up for the `name` in address books.

since: 2.22

###### camel_session_ref_main_context

Returns the `GMainContext` on which event sources for `session` are to be attached.

since: 3.8

###### camel_session_ref_network_monitor

References a `GNetworkMonitor` instance, which had been previously set by camel_session_set_network_monitor(). If none is set, then the default `GNetworkMonitor` is returned, as provided by g_network_monitor_get_default(). The returned pointer is referenced for thread safety, unref it with `g_object_unref()` when no longer needed.

since: 3.22

###### camel_session_ref_service

Looks up a `CamelService` by its unique identifier string. The service must have been previously added using camel_session_add_service().

since: 3.6

###### camel_session_ref_service_by_url

Looks up a `CamelService` by trying to match its `CamelURL` 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().

since: 3.6

###### camel_session_remove_service

Removes a `CamelService` previously added by camel_session_add_service().

since: 3.2

###### camel_session_remove_services

Removes all `CamelService` instances added by camel_session_add_service().

since: 3.2

###### camel_session_set_junk_filter

Installs the `CamelJunkFilter` instance used to classify messages as junk or not junk during filtering.

since: 3.2

###### camel_session_set_junk_headers

No description available.

since: 2.22

###### camel_session_set_network_monitor

Sets a network monitor instance for the `session`. This can be used to override which `GNetworkMonitor` should be used to check network availability and whether a server is reachable.

since: 3.22

###### camel_session_set_online

Sets the online status of `session` to `online`.

###### camel_session_submit_job

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:.

since: 3.2

###### camel_session_trust_prompt

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

since: 3.8

###### camel_session_user_alert

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

since: 3.12

##### Methods inherited from GObject (43)

Please see GObject for a full list of methods.

#### Properties

###### Camel.Session:junk-filter

Classifies messages as junk or not junk.

###### Camel.Session:main-context

The main loop context on which to attach event sources.

###### Camel.Session:network-monitor

The `GNetworkMonitor`.

###### Camel.Session:online

Whether the shell is online.

###### Camel.Session:user-cache-dir

User-specific base directory for mail cache.

###### Camel.Session:user-data-dir

User-specific base directory for mail data.

#### Signals

###### Camel.Session::job-finished

No description available.

###### Camel.Session::job-started

No description available.

###### Camel.Session::user-alert

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.

##### 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 CamelSessionClass {
      GObjectClass parent_class;
      CamelService* (* add_service) (
        CamelSession* session,
        const gchar* uid,
        const gchar* protocol,
        CamelProviderType type,
        GError** error
      );
      void (* remove_service) (
        CamelSession* session,
        CamelService* service
      );
      gchar* (* get_password) (
        CamelSession* session,
        CamelService* service,
        const gchar* prompt,
        const gchar* item,
        guint32 flags,
        GError** error
      );
      gboolean (* forget_password) (
        CamelSession* session,
        CamelService* service,
        const gchar* item,
        GError** error
      );
      CamelCertTrust (* trust_prompt) (
        CamelSession* session,
        CamelService* service,
        GTlsCertificate* certificate,
        GTlsCertificateFlags errors
      );
      CamelFilterDriver* (* get_filter_driver) (
        CamelSession* session,
        const gchar* type,
        CamelFolder* for_folder,
        GError** error
      );
      gboolean (* lookup_addressbook) (
        CamelSession* session,
        const gchar* name
      );
      gboolean (* authenticate_sync) (
        CamelSession* session,
        CamelService* service,
        const gchar* mechanism,
        GCancellable* cancellable,
        GError** error
      );
      gboolean (* forward_to_sync) (
        CamelSession* session,
        CamelFolder* folder,
        CamelMimeMessage* message,
        const gchar* address,
        GCancellable* cancellable,
        GError** error
      );
      gboolean (* get_oauth2_access_token_sync) (
        CamelSession* session,
        CamelService* service,
        gchar** out_access_token,
        gint* out_expires_in,
        GCancellable* cancellable,
        GError** error
      );
      gboolean (* get_recipient_certificates_sync) (
        CamelSession* session,
        guint32 flags,
        const GPtrArray* recipients,
        GSList** out_certificates,
        GCancellable* cancellable,
        GError** error
      );
      gboolean (* addressbook_contains_sync) (
        CamelSession* session,
        const gchar* book_uid,
        const gchar* email_address,
        GCancellable* cancellable,
        GError** error
      );
      gpointer reserved_methods;
      void (* job_started) (
        CamelSession* session,
        GCancellable* cancellable
      );
      void (* job_finished) (
        CamelSession* session,
        GCancellable* cancellable,
        const GError* error
      );
      void (* user_alert) (
        CamelSession* session,
        CamelService* service,
        CamelSessionAlertType type,
        const gchar* message
      );
      gpointer reserved_signals;

    }

No description available.

###### Class members

`parent_class: GObjectClass`

  No description available.

`add_service: CamelService* (* add_service) ( CamelSession* session, const gchar* uid, const gchar* protocol, CamelProviderType type, GError** error )`

  No description available.

`remove_service: void (* remove_service) ( CamelSession* session, CamelService* service )`

  No description available.

`get_password: gchar* (* get_password) ( CamelSession* session, CamelService* service, const gchar* prompt, const gchar* item, guint32 flags, GError** error )`

  No description available.

`forget_password: gboolean (* forget_password) ( CamelSession* session, CamelService* service, const gchar* item, GError** error )`

  No description available.

`trust_prompt: CamelCertTrust (* trust_prompt) ( CamelSession* session, CamelService* service, GTlsCertificate* certificate, GTlsCertificateFlags errors )`

  No description available.

`get_filter_driver: CamelFilterDriver* (* get_filter_driver) ( CamelSession* session, const gchar* type, CamelFolder* for_folder, GError** error )`

  No description available.

`lookup_addressbook: gboolean (* lookup_addressbook) ( CamelSession* session, const gchar* name )`

  No description available.

`authenticate_sync: gboolean (* authenticate_sync) ( CamelSession* session, CamelService* service, const gchar* mechanism, GCancellable* cancellable, GError** error )`

  No description available.

`forward_to_sync: gboolean (* forward_to_sync) ( CamelSession* session, CamelFolder* folder, CamelMimeMessage* message, const gchar* address, GCancellable* cancellable, GError** error )`

  No description available.

`get_oauth2_access_token_sync: gboolean (* get_oauth2_access_token_sync) ( CamelSession* session, CamelService* service, gchar** out_access_token, gint* out_expires_in, GCancellable* cancellable, GError** error )`

  No description available.

`get_recipient_certificates_sync: gboolean (* get_recipient_certificates_sync) ( CamelSession* session, guint32 flags, const GPtrArray* recipients, GSList** out_certificates, GCancellable* cancellable, GError** error )`

  No description available.

`addressbook_contains_sync: gboolean (* addressbook_contains_sync) ( CamelSession* session, const gchar* book_uid, const gchar* email_address, GCancellable* cancellable, GError** error )`

  No description available.

`reserved_methods: gpointer`

  No description available.

`job_started: void (* job_started) ( CamelSession* session, GCancellable* cancellable )`

  No description available.

`job_finished: void (* job_finished) ( CamelSession* session, GCancellable* cancellable, const GError* error )`

  No description available.

`user_alert: void (* user_alert) ( CamelSession* session, CamelService* service, CamelSessionAlertType type, const gchar* message )`

  No description available.

`reserved_signals: gpointer`

  No description available.

#### Virtual methods

###### Camel.SessionClass.add_service

Instantiates a new `CamelService` for `session`. The `uid` identifies the service for future lookup. The `protocol` indicates which `CamelProvider` holds the `GType` of the `CamelService` subclass to instantiate. The `type` explicitly designates the service as a `CamelStore` or `CamelTransport`.

since: 3.2

###### Camel.SessionClass.addressbook_contains_sync

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

since: 3.44

###### Camel.SessionClass.authenticate_sync

Authenticates `service`, which may involve repeated calls to `camel_service_authenticate()` or camel_service_authenticate_sync(). A `CamelSession` 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.

since: 3.4

###### Camel.SessionClass.forget_password

This function is used by a `CamelService` 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.

###### Camel.SessionClass.forward_to_sync

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

since: 3.6

###### Camel.SessionClass.get_filter_driver

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

###### Camel.SessionClass.get_oauth2_access_token_sync

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

since: 3.28

###### Camel.SessionClass.get_password

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

###### Camel.SessionClass.get_recipient_certificates_sync

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 `NULL` data for those which could not be found.

since: 3.30

###### Camel.SessionClass.job_finished

No description available.

###### Camel.SessionClass.job_started

No description available.

###### Camel.SessionClass.lookup_addressbook

Looks up for the `name` in address books.

since: 2.22

###### Camel.SessionClass.remove_service

Removes a `CamelService` previously added by camel_session_add_service().

since: 3.2

###### Camel.SessionClass.trust_prompt

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

since: 3.8

###### Camel.SessionClass.user_alert

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

since: 3.12