## CamelSession

CamelSession

## Synopsis

    struct              CamelSession;
    enum                CamelSessionAlertType;
    GMainContext *      camel_session_get_main_context      (CamelSession *session);
    const gchar *       camel_session_get_user_data_dir     (CamelSession *session);
    const gchar *       camel_session_get_user_cache_dir    (CamelSession *session);
    void                camel_session_get_socks_proxy       (CamelSession *session,
                                                             const gchar *for_host,
                                                             gchar **host_ret,
                                                             gint *port_ret);
    CamelService *      camel_session_add_service           (CamelSession *session,
                                                             const gchar *uid,
                                                             const gchar *protocol,
                                                             CamelProviderType type,
                                                             GError **error);
    void                camel_session_remove_service        (CamelSession *session,
                                                             CamelService *service);
    CamelService *      camel_session_ref_service           (CamelSession *session,
                                                             const gchar *uid);
    CamelService *      camel_session_ref_service_by_url    (CamelSession *session,
                                                             CamelURL *url,
                                                             CamelProviderType type);
    GList *             camel_session_list_services         (CamelSession *session);
    void                camel_session_remove_services       (CamelSession *session);
    gchar *             camel_session_get_password          (CamelSession *session,
                                                             CamelService *service,
                                                             const gchar *prompt,
                                                             const gchar *item,
                                                             guint32 flags,
                                                             GError **error);
    gboolean            camel_session_forget_password       (CamelSession *session,
                                                             CamelService *service,
                                                             const gchar *item,
                                                             GError **error);
    gint                camel_session_alert_user            (CamelSession *session,
                                                             CamelSessionAlertType type,
                                                             const gchar *prompt,
                                                             GSList *button_captions);
    gchar *             camel_session_build_password_prompt (const gchar *type,
                                                             const gchar *user,
                                                             const gchar *host);
    gboolean            camel_session_get_online            (CamelSession *session);
    void                camel_session_set_online            (CamelSession *session,
                                                             gboolean online);
    CamelFilterDriver * camel_session_get_filter_driver     (CamelSession *session,
                                                             const gchar *type,
                                                             GError **error);
    gboolean            camel_session_get_check_junk        (CamelSession *session);
    void                camel_session_set_check_junk        (CamelSession *session,
                                                             gboolean check_junk);
    CamelJunkFilter *   camel_session_get_junk_filter       (CamelSession *session);
    void                camel_session_set_junk_filter       (CamelSession *session,
                                                             CamelJunkFilter *junk_filter);
    guint               camel_session_idle_add              (CamelSession *session,
                                                             gint priority,
                                                             GSourceFunc function,
                                                             gpointer data,
                                                             GDestroyNotify notify);
    void                (*CamelSessionCallback)             (CamelSession *session,
                                                             GCancellable *cancellable,
                                                             gpointer user_data,
                                                             GError **error);
    void                camel_session_submit_job            (CamelSession *session,
                                                             CamelSessionCallback callback,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);
    gboolean            camel_session_get_network_available (CamelSession *session);
    void                camel_session_set_network_available (CamelSession *session,
                                                             gboolean network_available);
    const GHashTable *  camel_session_get_junk_headers      (CamelSession *session);
    void                camel_session_set_junk_headers      (CamelSession *session,
                                                             const gchar **headers,
                                                             const gchar **values,
                                                             gint len);
    gboolean            camel_session_lookup_addressbook    (CamelSession *session,
                                                             const gchar *name);
    gboolean            camel_session_authenticate_sync     (CamelSession *session,
                                                             CamelService *service,
                                                             const gchar *mechanism,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                camel_session_authenticate          (CamelSession *session,
                                                             CamelService *service,
                                                             const gchar *mechanism,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            camel_session_authenticate_finish   (CamelSession *session,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            camel_session_forward_to_sync       (CamelSession *session,
                                                             CamelFolder *folder,
                                                             CamelMimeMessage *message,
                                                             const gchar *address,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                camel_session_forward_to            (CamelSession *session,
                                                             CamelFolder *folder,
                                                             CamelMimeMessage *message,
                                                             const gchar *address,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            camel_session_forward_to_finish     (CamelSession *session,
                                                             GAsyncResult *result,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----CamelObject
             +----CamelSession

## Properties

      "check-junk"               gboolean              : Read / Write / Construct
      "junk-filter"              CamelJunkFilter*      : Read / Write
      "main-context"             GMainContext*         : Read
      "network-available"        gboolean              : Read / Write / Construct
      "online"                   gboolean              : Read / Write / Construct
      "user-cache-dir"           gchar*                : Read / Write / Construct
      "user-data-dir"            gchar*                : Read / Write / Construct

## Signals

      "job-finished"                                   : Run Last
      "job-started"                                    : Run Last

## Description

## Details

### struct CamelSession

    struct CamelSession;

### enum CamelSessionAlertType

    typedef enum {
    	CAMEL_SESSION_ALERT_INFO,
    	CAMEL_SESSION_ALERT_WARNING,
    	CAMEL_SESSION_ALERT_ERROR
    } CamelSessionAlertType;

### camel_session_get_main_context ()

    GMainContext *      camel_session_get_main_context      (CamelSession *session);

Returns the GMainContext from which signals are emitted. This was the thread-default GMainContext for the thread where `session` was instantiated.

`session` : | a CamelSession
Returns : | the GMainContext for signal emissions

Since 3.6

### camel_session_get_user_data_dir ()

    const gchar *       camel_session_get_user_data_dir     (CamelSession *session);

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

`session` : | a CamelSession
Returns : | the base directory for mail data

Since 3.2

### camel_session_get_user_cache_dir ()

    const gchar *       camel_session_get_user_cache_dir    (CamelSession *session);

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

`session` : | a CamelSession
Returns : | the base directory for mail cache

Since 3.4

### camel_session_get_socks_proxy ()

    void                camel_session_get_socks_proxy       (CamelSession *session,
                                                             const gchar *for_host,
                                                             gchar **host_ret,
                                                             gint *port_ret);

Queries the SOCKS proxy that is configured for a `session`. This will put `NULL` in `hosts_ret` if there is no proxy configured or when the `for_host` is listed in proxy ignore list.

`session` : | A CamelSession
`for_host` : | Host name to which the connection will be requested
`host_ret` : | Location to return the SOCKS proxy hostname
`port_ret` : | Location to return the SOCKS proxy port

Since 2.32

### camel_session_add_service ()

    CamelService *      camel_session_add_service           (CamelSession *session,
                                                             const gchar *uid,
                                                             const gchar *protocol,
                                                             CamelProviderType type,
                                                             GError **error);

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.

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

If no CamelProvider is available to handle the given `protocol`, or if the CamelProvider does not specify a valid GType for `type`, the function sets `error` and returns `NULL`.

The returned CamelService is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

`session` : | a CamelSession
`uid` : | a unique identifier string
`protocol` : | the service protocol
`type` : | the service type
`error` : | return location for a GError, or `NULL`
Returns : | a CamelService instance, or `NULL`

Since 3.2

### camel_session_remove_service ()

    void                camel_session_remove_service        (CamelSession *session,
                                                             CamelService *service);

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

`session` : | a CamelSession
`service` : | the CamelService to remove

Since 3.2

### camel_session_ref_service ()

    CamelService *      camel_session_ref_service           (CamelSession *session,
                                                             const gchar *uid);

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

The returned CamelService is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

`session` : | a CamelSession
`uid` : | a unique identifier string
Returns : | a CamelService instance, or `NULL`

Since 3.6

### camel_session_ref_service_by_url ()

    CamelService *      camel_session_ref_service_by_url    (CamelSession *session,
                                                             CamelURL *url,
                                                             CamelProviderType type);

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

The returned CamelService is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

Note this function is significantly slower than `camel_session_ref_service()`.

`session` : | a CamelSession
`url` : | a CamelURL
`type` : | a CamelProviderType
Returns : | a CamelService instance, or `NULL`

Since 3.6

### camel_session_list_services ()

    GList *             camel_session_list_services         (CamelSession *session);

Returns a list of all CamelService 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 `g_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:

    1

    g_list_free_full (list, g_object_unref);

`session` : | a CamelSession
Returns : | an unsorted list of CamelService objects

Since 3.2

### camel_session_remove_services ()

    void                camel_session_remove_services       (CamelSession *session);

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

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

`session` : | a CamelSession

Since 3.2

### camel_session_get_password ()

    gchar *             camel_session_get_password          (CamelSession *session,
                                                             CamelService *service,
                                                             const gchar *prompt,
                                                             const gchar *item,
                                                             guint32 flags,
                                                             GError **error);

This function is used by a CamelService 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 `G_IO_ERROR_CANCELLED` if the user did not provide the information. The caller must `g_free()` the information returned when it is done with it.

`session` : | a CamelSession
`service` : | the CamelService this query is being made by
`prompt` : | prompt to provide to user
`item` : | an identifier, unique within this service, for the information
`flags` : | `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
`error` : | return location for a GError, or `NULL`
Returns : | the authentication information or `NULL`

### camel_session_forget_password ()

    gboolean            camel_session_forget_password       (CamelSession *session,
                                                             CamelService *service,
                                                             const gchar *item,
                                                             GError **error);

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.

`service` and `item` identify the rejected authentication information, as with `camel_session_get_password()`.

`session` : | a CamelSession
`service` : | the CamelService rejecting the password
`item` : | an identifier, unique within this service, for the information
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### camel_session_alert_user ()

    gint                camel_session_alert_user            (CamelSession *session,
                                                             CamelSessionAlertType type,
                                                             const gchar *prompt,
                                                             GSList *button_captions);

Presents the given `prompt` to the user, in the style indicated by `type`. If `cancel` is `TRUE`, the user will be able to accept or cancel. Otherwise, the message is purely informational.

`session` : | a CamelSession
`type` : | the type of alert (info, warning, or error)
`prompt` : | the message for the user
`button_captions` : | List of button captions to use. If NULL, only "Dismiss" button is shown.
Returns : | Index of pressed button from `button_captions`, -1 if NULL.

### camel_session_build_password_prompt ()

    gchar *             camel_session_build_password_prompt (const gchar *type,
                                                             const gchar *user,
                                                             const gchar *host);

Constructs a localized password prompt from `type`, `user` and `host`, suitable for passing to `camel_session_get_password()`. The resulting string contains markup tags. Use `g_free()` to free it.

`type` : | account type (e.g. "IMAP")
`user` : | user name for the account
`host` : | host name for the account
Returns : | a newly-allocated password prompt string

Since 2.22

### camel_session_get_online ()

    gboolean            camel_session_get_online            (CamelSession *session);

`session` : | a CamelSession
Returns : | whether or not `session` is online

### camel_session_set_online ()

    void                camel_session_set_online            (CamelSession *session,
                                                             gboolean online);

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

`session` : | a CamelSession
`online` : | whether or not the session should be online

### camel_session_get_filter_driver ()

    CamelFilterDriver * camel_session_get_filter_driver     (CamelSession *session,
                                                             const gchar *type,
                                                             GError **error);

`session` : | a CamelSession
`type` : | the type of filter (eg, "incoming")
`error` : | return location for a GError, or `NULL`
Returns : | a filter driver, loaded with applicable rules

### camel_session_get_check_junk ()

    gboolean            camel_session_get_check_junk        (CamelSession *session);

Do we have to check incoming messages to be junk?

`session` : | a CamelSession
Returns : | whether or not we are checking incoming messages for junk

### camel_session_set_check_junk ()

    void                camel_session_set_check_junk        (CamelSession *session,
                                                             gboolean check_junk);

Set check_junk flag, if set, incoming mail will be checked for being junk.

`session` : | a CamelSession
`check_junk` : | whether to check incoming messages for junk

### camel_session_get_junk_filter ()

    CamelJunkFilter *   camel_session_get_junk_filter       (CamelSession *session);

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

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

`session` : | a CamelSession
Returns : | a CamelJunkFilter, or `NULL`

Since 3.2

### camel_session_set_junk_filter ()

    void                camel_session_set_junk_filter       (CamelSession *session,
                                                             CamelJunkFilter *junk_filter);

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

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

`session` : | a CamelSession
`junk_filter` : | a CamelJunkFilter, or `NULL`

Since 3.2

### camel_session_idle_add ()

    guint               camel_session_idle_add              (CamelSession *session,
                                                             gint priority,
                                                             GSourceFunc function,
                                                             gpointer data,
                                                             GDestroyNotify notify);

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 `g_idle_source_new()` and attaches it to `session`'s own "main-context" using `g_source_attach()`.

The `priority` is typically in the range between `G_PRIORITY_DEFAULT_IDLE` and `G_PRIORITY_HIGH_IDLE`.

`session` : | a CamelSession
`priority` : | the priority of the idle source
`function` : | a function to call
`data` : | data to pass to `function`
`notify` : | function to call when the idle is removed, or `NULL`
Returns : | the ID (greater than 0) of the event source

Since 3.6

### CamelSessionCallback ()

    void                (*CamelSessionCallback)             (CamelSession *session,
                                                             GCancellable *cancellable,
                                                             gpointer user_data,
                                                             GError **error);

This is the callback signature for jobs submitted to the CamelSession via `camel_session_submit_job()`. The `error` pointer is always non-`NULL`, so it's safe to dereference to check if a GError has been set.

`session` : | a CamelSession
`cancellable` : | a CamelOperation cast as a GCancellable
`user_data` : | data passed to `camel_session_submit_job()`
`error` : | return location for a GError

Since 3.2

### camel_session_submit_job ()

    void                camel_session_submit_job            (CamelSession *session,
                                                             CamelSessionCallback callback,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);

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 "job-started" signal is emitted from the thread in which `session` was created. This is typically the same thread that hosts the global default GMainContext, 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 "job-finished" signal is emitted from the same thread as "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.

`session` : | a CamelSession
`callback` : | a CamelSessionCallback
`user_data` : | user data passed to the callback
`notify` : | a GDestroyNotify function

Since 3.2

### camel_session_get_network_available ()

    gboolean            camel_session_get_network_available (CamelSession *session);

`session` : | a CamelSession

Since 2.32

### camel_session_set_network_available ()

    void                camel_session_set_network_available (CamelSession *session,
                                                             gboolean network_available);

`session` : | a CamelSession
`network_available` : | whether a network is available

Since 2.32

### camel_session_get_junk_headers ()

    const GHashTable *  camel_session_get_junk_headers      (CamelSession *session);

Since 2.22

### camel_session_set_junk_headers ()

    void                camel_session_set_junk_headers      (CamelSession *session,
                                                             const gchar **headers,
                                                             const gchar **values,
                                                             gint len);

Since 2.22

### camel_session_lookup_addressbook ()

    gboolean            camel_session_lookup_addressbook    (CamelSession *session,
                                                             const gchar *name);

Since 2.22

### camel_session_authenticate_sync ()

    gboolean            camel_session_authenticate_sync     (CamelSession *session,
                                                             CamelService *service,
                                                             const gchar *mechanism,
                                                             GCancellable *cancellable,
                                                             GError **error);

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.

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

`session` : | a CamelSession
`service` : | a CamelService
`mechanism` : | a SASL mechanism name, or `NULL`
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

Since 3.4

### camel_session_authenticate ()

    void                camel_session_authenticate          (CamelSession *session,
                                                             CamelService *service,
                                                             const gchar *mechanism,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

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.

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

`session` : | a CamelSession
`service` : | a CamelService
`mechanism` : | a SASL mechanism name, or `NULL`
`io_priority` : | the I/O priority for the request
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | data to pass to the callback function

Since 3.4

### camel_session_authenticate_finish ()

    gboolean            camel_session_authenticate_finish   (CamelSession *session,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `camel_session_authenticate()`.

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

`session` : | a CamelSession
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

Since 3.4

### camel_session_forward_to_sync ()

    gboolean            camel_session_forward_to_sync       (CamelSession *session,
                                                             CamelFolder *folder,
                                                             CamelMimeMessage *message,
                                                             const gchar *address,
                                                             GCancellable *cancellable,
                                                             GError **error);

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

If an error occurs, the function sets `error` and returns `FALSE`.

`session` : | a CamelSession
`folder` : | the CamelFolder where `message` is located
`message` : | the CamelMimeMessage to forward
`address` : | the recipient's email address
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

Since 3.6

### camel_session_forward_to ()

    void                camel_session_forward_to            (CamelSession *session,
                                                             CamelFolder *folder,
                                                             CamelMimeMessage *message,
                                                             const gchar *address,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

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.

`session` : | a CamelSession
`folder` : | the CamelFolder where `message` is located
`message` : | the CamelMimeMessage to forward
`address` : | the recipient's email address
`io_priority` : | the I/O priority for the request
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | data to pass to the callback function

Since 3.6

### camel_session_forward_to_finish ()

    gboolean            camel_session_forward_to_finish     (CamelSession *session,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `camel_session_forward_to()`.

If an error occurred, the function sets `error` and returns `FALSE`.

`session` : | a CamelSession
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

Since 3.6

## Property Details

### The `"check-junk"` property

      "check-junk"               gboolean              : Read / Write / Construct

Check incoming messages for junk.

Default value: FALSE

### The `"junk-filter"` property

      "junk-filter"              CamelJunkFilter*      : Read / Write

Classifies messages as junk or not junk.

### The `"main-context"` property

      "main-context"             GMainContext*         : Read

The GMainContext used for signal emissions.

### The `"network-available"` property

      "network-available"        gboolean              : Read / Write / Construct

Whether the network is available.

Default value: TRUE

### The `"online"` property

      "online"                   gboolean              : Read / Write / Construct

Whether the shell is online.

Default value: TRUE

### The `"user-cache-dir"` property

      "user-cache-dir"           gchar*                : Read / Write / Construct

User-specific base directory for mail cache.

Default value: NULL

### The `"user-data-dir"` property

      "user-data-dir"            gchar*                : Read / Write / Construct

User-specific base directory for mail data.

Default value: NULL

## Signal Details

### The `"job-finished"` signal

    void                user_function                      (CamelSession *camelsession,
                                                            GCancellable *arg1,
                                                            gpointer      arg2,
                                                            gpointer      user_data)         : Run Last

### The `"job-started"` signal

    void                user_function                      (CamelSession *camelsession,
                                                            GCancellable *arg1,
                                                            gpointer      user_data)         : Run Last