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.

Since: 3.2

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.

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.

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.

Since: 3.4

camel_session_set_network_monitor ()

void
camel_session_set_network_monitor (CamelSession *session,
                                   GNetworkMonitor *network_monitor);

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

Since: 3.22

camel_session_ref_network_monitor ()

GNetworkMonitor *
camel_session_ref_network_monitor (CamelSession *session);

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

Since: 3.22

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

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

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.

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

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

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.

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.

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

camel_session_trust_prompt ()

CamelCertTrust
camel_session_trust_prompt (CamelSession *session,
                            CamelService *service,
                            GTlsCertificate *certificate,
                            GTlsCertificateFlags errors);

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

If an error occurs during prompting or if the user declines to respond, the function returns CAMEL_CERT_TRUST_UNKNOWN and the certificate will be rejected.

Since: 3.8

camel_session_user_alert ()

void
camel_session_user_alert (CamelSession *session,
                          CamelService *service,
                          CamelSessionAlertType type,
                          const gchar *message);

Emits a “user_alert” signal from an idle source on the main loop. The idle source's priority is G_PRIORITY_LOW.

The purpose of the signal is to propagate a server-issued alert message from service to a user interface. The type hints at the nature of the alert message.

Since: 3.12

camel_session_get_online ()

gboolean
camel_session_get_online (CamelSession *session);

camel_session_set_online ()

void
camel_session_set_online (CamelSession *session,
                          gboolean online);

Sets the online status of session to online .

camel_session_get_filter_driver ()

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

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.

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.

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.

Since: 3.6

camel_session_submit_job ()

void
camel_session_submit_job (CamelSession *session,
                          const gchar *description,
                          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.

Since: 3.2

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.

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.

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.

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.

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.

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.

Since: 3.6

The “junk-filter” property

  “junk-filter”              CamelJunkFilter *

Classifies messages as junk or not junk.

Flags: Read / Write

The “main-context” property

  “main-context”             GMainContext *

The main loop context on which to attach event sources.

Flags: Read

The “network-monitor” property

  “network-monitor”          GNetworkMonitor *

Flags: Read / Write

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

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

The “user-alert” signal

void
user_function (CamelSession         *session,
               CamelService         *service,
               CamelSessionAlertType type,
               gchar                *message,
               gpointer              user_data)

This purpose of this signal is to propagate a server-issued alert message from service to a user interface. The type hints at the severity of the alert message.

Flags: Run Last