CamelSession

CamelSession

Functions

Properties

gboolean check-junk Read / Write / Construct
CamelJunkFilter * junk-filter Read / Write
gboolean network-available Read / Write / Construct
gboolean online Read / Write / Construct
gchar * user-cache-dir Read / Write / Construct
gchar * user-data-dir Read / Write / Construct

Signals

void job-finished Run Last
void job-started Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── CamelObject
        ╰── CamelSession

Description

Functions

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

session

a CamelSession

 

service

the CamelService to remove

 

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

Parameters

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

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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 .

Parameters

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

Parameters

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?

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

session

a CamelSession

 

junk_filter

a CamelJunkFilter, or NULL

 

Since 3.2


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.

Parameters

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.

Parameters

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

Parameters

session

a CamelSession

 

Since 2.32


camel_session_set_network_available ()

void
camel_session_set_network_available (CamelSession *session,
                                     gboolean network_available);

Parameters

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

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

Since 2.26


camel_session_lock ()

void
camel_session_lock (CamelSession *session,
                    CamelSessionLock lock);

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

Parameters

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

Parameters

session

a CamelSession

 

lock

lock type to unlock

 

Since 2.32


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.

Parameters

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.

Parameters

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.

Parameters

session

a CamelSession

 

result

a GAsyncResult

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since 3.4

Types and Values

struct CamelSession

struct CamelSession;

enum CamelSessionAlertType

Members

CAMEL_SESSION_ALERT_INFO

   

CAMEL_SESSION_ALERT_WARNING

   

CAMEL_SESSION_ALERT_ERROR

   

enum CamelSessionLock

Members

CAMEL_SESSION_SESSION_LOCK

   

CAMEL_SESSION_THREAD_LOCK

   

Since 2.32

Property Details

The “check-junk” property

  “check-junk”               gboolean

Check incoming messages for junk.

Flags: Read / Write / Construct

Default value: FALSE


The “junk-filter” property

  “junk-filter”              CamelJunkFilter *

Classifies messages as junk or not junk.

Flags: Read / Write


The “network-available” property

  “network-available”        gboolean

Whether the network is available.

Flags: Read / Write / Construct

Default value: TRUE


The “online” property

  “online”                   gboolean

Whether the shell is online.

Flags: Read / Write / Construct

Default value: TRUE


The “user-cache-dir” property

  “user-cache-dir”           gchar *

User-specific base directory for mail cache.

Flags: Read / Write / Construct

Default value: NULL


The “user-data-dir” property

  “user-data-dir”            gchar *

User-specific base directory for mail data.

Flags: Read / Write / Construct

Default value: NULL

Signal Details

The “job-finished” signal

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

Flags: Run Last


The “job-started” signal

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

Flags: Run Last