## CamelSession

CamelSession

## Synopsis

    struct              CamelSession;
    enum                CamelSessionAlertType;
    const gchar *       camel_session_get_user_data_dir     (CamelSession *session);
    void                camel_session_set_socks_proxy       (CamelSession *session,
                                                             const gchar *socks_host,
                                                             gint socks_port);
    void                camel_session_get_socks_proxy       (CamelSession *session,
                                                             gchar **host_ret,
                                                             gint *port_ret);
    CamelService *      camel_session_add_service           (CamelSession *session,
                                                             const gchar *uid,
                                                             const gchar *uri_string,
                                                             CamelProviderType type,
                                                             GError **error);
    CamelService *      camel_session_get_service           (CamelSession *session,
                                                             const gchar *uid);
    CamelService *      camel_session_get_service_by_url    (CamelSession *session,
                                                             CamelURL *url,
                                                             CamelProviderType type);
    GList *             camel_session_list_services         (CamelSession *session);
    gchar *             camel_session_get_password          (CamelSession *session,
                                                             CamelService *service,
                                                             const gchar *domain,
                                                             const gchar *prompt,
                                                             const gchar *item,
                                                             guint32 flags,
                                                             GError **error);
    gboolean            camel_session_forget_password       (CamelSession *session,
                                                             CamelService *service,
                                                             const gchar *domain,
                                                             const gchar *item,
                                                             GError **error);
    gboolean            camel_session_alert_user            (CamelSession *session,
                                                             CamelSessionAlertType type,
                                                             const gchar *prompt,
                                                             gboolean cancel);
    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);
    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_state);
    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_forward_to            (CamelSession *session,
                                                             CamelFolder *folder,
                                                             CamelMimeMessage *message,
                                                             const gchar *address,
                                                             GError **error);
    enum                CamelSessionLock;
    void                camel_session_lock                  (CamelSession *session,
                                                             CamelSessionLock lock);
    void                camel_session_unlock                (CamelSession *session,
                                                             CamelSessionLock lock);

## Object Hierarchy

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

## Properties

      "check-junk"               gboolean              : Read / Write / Construct
      "network-available"        gboolean              : Read / Write / Construct
      "online"                   gboolean              : 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_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_set_socks_proxy ()

    void                camel_session_set_socks_proxy       (CamelSession *session,
                                                             const gchar *socks_host,
                                                             gint socks_port);

Sets a SOCKS proxy that will be used throughout the `session` for TCP connections.

`session` : | A CamelSession
`socks_host` : | Hostname of the SOCKS proxy, or NULL for none.
`socks_port` : | Port number of the SOCKS proxy

Since 2.32

### camel_session_get_socks_proxy ()

    void                camel_session_get_socks_proxy       (CamelSession *session,
                                                             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.

`session` : | A CamelSession
`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 *uri_string,
                                                             CamelProviderType type,
                                                             GError **error);

Instantiates a new CamelService for `session`. The `uid` identifies the service for future lookup. The `uri_string` describes which provider to use, authentication details, provider-specific options, etc. 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 `uri_string` and `type`.

If the `uri_string` is invalid or no CamelProvider is available to handle the `uri_string`, the function sets `error` and returns `NULL`.

`session` : | a CamelSession
`uid` : | a unique identifier string
`uri_string` : | a URI string describing the service
`type` : | the provider type (CAMEL_PROVIDER_STORE or CAMEL_PROVIDER_TRANSPORT) to get, since some URLs may be able to specify either type
`error` : | return location for a GError, or `NULL`
Returns : | a CamelService instance, or `NULL`

Since 3.2

### camel_session_get_service ()

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

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

### camel_session_get_service_by_url ()

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

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

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

Since 3.2

### 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()`. Free the returned list using `g_list_free()`.

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

### camel_session_get_password ()

    gchar *             camel_session_get_password          (CamelSession *session,
                                                             CamelService *service,
                                                             const gchar *domain,
                                                             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
`domain` : | domain of password request. May be null to use the default.
`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 *domain,
                                                             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 ()

    gboolean            camel_session_alert_user            (CamelSession *session,
                                                             CamelSessionAlertType type,
                                                             const gchar *prompt,
                                                             gboolean cancel);

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
`cancel` : | whether or not to provide a "Cancel" option in addition to an "OK" option.
Returns : | `TRUE` if the user accepts, `FALSE` if they cancel.

### 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

### 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_state);

`session` : | a CamelSession

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_forward_to ()

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

Since 2.26

### enum CamelSessionLock

    typedef enum {
    	CAMEL_SESSION_SESSION_LOCK,
    	CAMEL_SESSION_THREAD_LOCK
    } CamelSessionLock;

Since 2.32

### camel_session_lock ()

    void                camel_session_lock                  (CamelSession *session,
                                                             CamelSessionLock lock);

Locks session's lock. Unlock it with `camel_session_unlock()`.

`session` : | a CamelSession
`lock` : | lock type to lock

Since 2.32

### camel_session_unlock ()

    void                camel_session_unlock                (CamelSession *session,
                                                             CamelSessionLock lock);

Unlocks session's lock, previously locked with `camel_session_lock()`.

`session` : | a CamelSession
`lock` : | lock type to unlock

Since 2.32

## Property Details

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

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

Check incoming messages for junk.

Default value: FALSE

### 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-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

`camelsession` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

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

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

`camelsession` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.