CamelSession

CamelSession

Synopsis

struct              CamelSession;
enum                CamelSessionAlertType;
GMainContext *      camel_session_ref_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,
                                                         GList *button_captions,
                                                         GCancellable *cancellable);
CamelCertTrust      camel_session_trust_prompt          (CamelSession *session,
                                                         const gchar *host,
                                                         const gchar *certificate,
                                                         guint32 certificate_errors,
                                                         GList *issuers,
                                                         GCancellable *cancellable);
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);

GMainContext *      camel_session_get_main_context      (CamelSession *session);

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_ALERT_INFO

CAMEL_SESSION_ALERT_WARNING

CAMEL_SESSION_ALERT_ERROR


camel_session_ref_main_context ()

GMainContext *      camel_session_ref_main_context      (CamelSession *session);

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

session :

a CamelSession

Returns :

a GMainContext

Since 3.8


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,
                                                         GList *button_captions,
                                                         GCancellable *cancellable);

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.

cancellable :

optional GCancellable object, or NULL. [allow-non]

Returns :

Index of pressed button from button_captions, -1 if NULL.

camel_session_trust_prompt ()

CamelCertTrust      camel_session_trust_prompt          (CamelSession *session,
                                                         const gchar *host,
                                                         const gchar *certificate,
                                                         guint32 certificate_errors,
                                                         GList *issuers,
                                                         GCancellable *cancellable);

Prompts user about trust of a certificate. The certificate is not considered trusted, due to reasons set in certificate_errors. There can be passed a list of issuers, which has as items also base64-encoded DER certificates. The first item in the list is an issuer of the certificate, the second item is an issuer of the first item, and so on.

session :

a CamelSession

host :

host name, to which the certificate belongs

certificate :

base64-encoded DER certificate on which to ask

certificate_errors :

errors found with the certificate; a bit-OR of a GTlsCertificateFlags

issuers :

chain of issuers, or NULL. [allow-none]

cancellable :

optional GCancellable object, or NULL. [allow-non]

Returns :

What trust level should be used for this certificate. It returns CAMEL_CERT_TRUST_UNKNOWN on error or if user cancelled the dialog prompt.

Since 3.8


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


camel_session_get_main_context ()

GMainContext *      camel_session_get_main_context      (CamelSession *session);

Warning

camel_session_get_main_context has been deprecated since version 3.8 and should not be used in newly-written code. Use camel_session_ref_main_context() instead.

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

session :

a CamelSession

Returns :

a GMainContext

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 main loop context on which to attach event sources.


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