CamelSession: Camel Reference Manual

## CamelSession CamelSession |

## Functions

void | (*CamelSessionCallback) ()
GMainContext * | camel_session_ref_main_context ()
const gchar * | camel_session_get_user_data_dir ()
const gchar * | camel_session_get_user_cache_dir ()
void | camel_session_set_network_monitor ()
GNetworkMonitor * | camel_session_ref_network_monitor ()
CamelService * | camel_session_add_service ()
void | camel_session_remove_service ()
CamelService * | camel_session_ref_service ()
CamelService * | camel_session_ref_service_by_url ()
GList * | camel_session_list_services ()
void | camel_session_remove_services ()
gchar * | camel_session_get_password ()
gboolean | camel_session_forget_password ()
CamelCertTrust | camel_session_trust_prompt ()
void | camel_session_user_alert ()
gboolean | camel_session_get_online ()
void | camel_session_set_online ()
CamelFilterDriver * | camel_session_get_filter_driver ()
CamelJunkFilter * | camel_session_get_junk_filter ()
void | camel_session_set_junk_filter ()
guint | camel_session_idle_add ()
void | camel_session_submit_job ()
const GHashTable * | camel_session_get_junk_headers ()
void | camel_session_set_junk_headers ()
gboolean | camel_session_lookup_addressbook ()
gboolean | camel_session_authenticate_sync ()
void | camel_session_authenticate ()
gboolean | camel_session_authenticate_finish ()
gboolean | camel_session_forward_to_sync ()
void | camel_session_forward_to ()
gboolean | camel_session_forward_to_finish ()

## Description

## Functions

### 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_ref_main_context ()

    GMainContext *
    camel_session_ref_main_context (CamelSession *session);

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

#### Parameters

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.

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

#### Parameters

session | a CamelSession |
network_monitor | a GNetworkMonitor or `NULL`. | [nullable]

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.

#### Parameters

session | a CamelSession |

#### Returns

A referenced GNetworkMonitor instance to use for network availability tests.

[transfer full]

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.

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

[transfer full]

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

#### Parameters

session | a CamelSession |
uid | a unique identifier string |

#### Returns

a CamelService instance, or `NULL`.

[transfer full]

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

#### Parameters

session | a CamelSession |
url | a CamelURL |
type | a CamelProviderType |

#### Returns

a CamelService instance, or `NULL`.

[transfer full]

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:

      g_list_free_full (list, g_object_unref);

#### Parameters

session | a CamelSession |

#### Returns

an unsorted list of CamelService objects.

[element-type CamelService][transfer full]

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

#### Parameters

session | a CamelSession |
service | a CamelService |
certificate | the peer's GTlsCertificate |
errors | the problems with `certificate` |

#### Returns

the user's trust level for `certificate`

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.

#### Parameters

session | a CamelSession |
service | a CamelService |
type | a CamelSessionAlertType |
message | the message for the user |

Since: 3.12

### 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,
                                     CamelFolder *for_folder,
                                     GError **error);

The optional `for_folder` can be used to determine which filters to add and which not.

#### Parameters

session | a CamelSession |
type | the type of filter (eg, "incoming") |
for_folder | an optional CamelFolder, for which the filter driver will run, or `NULL`. | [nullable]
error | return location for a GError, or `NULL` |

#### Returns

a filter driver, loaded with applicable rules.

[transfer none]

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

[transfer none]

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

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

#### Parameters

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

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

#### Parameters

session | a CamelSession |
description | human readable description of the job, shown to a user |
callback | a CamelSessionCallback |
user_data | user data passed to the callback |
notify | a GDestroyNotify function |

Since: 3.2

### camel_session_get_junk_headers ()

    const GHashTable *
    camel_session_get_junk_headers (CamelSession *session);

#### Parameters

session | a CamelSession |

#### Returns

Currently used junk headers as a hash table, previously set by `camel_session_set_junk_headers()`.

[element-type utf8 utf8][transfer none]

Since: 2.22

### camel_session_set_junk_headers ()

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

#### Parameters

session | a CamelSession |
headers | . | [array length=len]
values | . | [array]
len | the length of the headers and values arrays |

Since: 2.22

### camel_session_lookup_addressbook ()

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

Looks up for the `name` in address books.

#### Parameters

session | a CamelSession |
name | a name/address to lookup for |

#### Returns

whether found the `name` in any address book.

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

#### Parameters

session | a CamelSession |
service | a CamelService |
mechanism | a SASL mechanism name, or `NULL`. | [nullable]
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`. | [nullable]
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

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

#### Parameters

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.

#### Parameters

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

#### Parameters

session | a CamelSession |
result | a GAsyncResult |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` on failure

Since: 3.6

## Types and Values