![]() |
![]() |
![]() |
Camel Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
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
);
"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
typedef enum { CAMEL_SESSION_ALERT_INFO, CAMEL_SESSION_ALERT_WARNING, CAMEL_SESSION_ALERT_ERROR } CamelSessionAlertType;
GMainContext * camel_session_ref_main_context (CamelSession *session
);
Returns the GMainContext on which event sources for session
are to
be attached.
|
a CamelSession |
Returns : |
a GMainContext |
Since 3.8
const gchar * camel_session_get_user_data_dir (CamelSession *session
);
Returns the base directory under which to store user-specific mail data.
|
a CamelSession |
Returns : |
the base directory for mail data |
Since 3.2
const gchar * camel_session_get_user_cache_dir (CamelSession *session
);
Returns the base directory under which to store user-specific mail cache.
|
a CamelSession |
Returns : |
the base directory for mail cache |
Since 3.4
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.
|
A CamelSession |
|
Host name to which the connection will be requested |
|
Location to return the SOCKS proxy hostname |
|
Location to return the SOCKS proxy port |
Since 2.32
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.
|
a CamelSession |
|
a unique identifier string |
|
the service protocol |
|
the service type |
|
return location for a GError, or NULL
|
Returns : |
a CamelService instance, or NULL
|
Since 3.2
void camel_session_remove_service (CamelSession *session
,CamelService *service
);
Removes a CamelService previously added by camel_session_add_service()
.
|
a CamelSession |
|
the CamelService to remove |
Since 3.2
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.
|
a CamelSession |
|
a unique identifier string |
Returns : |
a CamelService instance, or NULL
|
Since 3.6
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()
.
|
a CamelSession |
|
a CamelURL |
|
a CamelProviderType |
Returns : |
a CamelService instance, or NULL
|
Since 3.6
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); |
|
a CamelSession |
Returns : |
an unsorted list of CamelService objects |
Since 3.2
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.
|
a CamelSession |
Since 3.2
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.
|
a CamelSession |
|
the CamelService this query is being made by |
|
prompt to provide to user |
|
an identifier, unique within this service, for the information |
|
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 |
|
return location for a GError, or NULL
|
Returns : |
the authentication information or NULL
|
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()
.
|
a CamelSession |
|
the CamelService rejecting the password |
|
an identifier, unique within this service, for the information |
|
return location for a GError, or NULL
|
Returns : |
TRUE on success, FALSE on failure |
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.
|
a CamelSession |
|
the type of alert (info, warning, or error) |
|
the message for the user |
|
List of button captions to use. If NULL, only "Dismiss" button is shown. |
|
optional GCancellable object, or NULL . [allow-non]
|
Returns : |
Index of pressed button from button_captions , -1 if NULL. |
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.
|
a CamelSession |
|
host name, to which the certificate belongs |
|
base64-encoded DER certificate on which to ask |
|
errors found with the certificate; a bit-OR of a GTlsCertificateFlags |
|
chain of issuers, or NULL . [allow-none]
|
|
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
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.
|
account type (e.g. "IMAP") |
|
user name for the account |
|
host name for the account |
Returns : |
a newly-allocated password prompt string |
Since 2.22
gboolean camel_session_get_online (CamelSession *session
);
|
a CamelSession |
Returns : |
whether or not session is online |
void camel_session_set_online (CamelSession *session
,gboolean online
);
Sets the online status of session
to online
.
|
a CamelSession |
|
whether or not the session should be online |
CamelFilterDriver * camel_session_get_filter_driver (CamelSession *session
,const gchar *type
,GError **error
);
|
a CamelSession |
|
the type of filter (eg, "incoming") |
|
return location for a GError, or NULL
|
Returns : |
a filter driver, loaded with applicable rules |
gboolean camel_session_get_check_junk (CamelSession *session
);
Do we have to check incoming messages to be junk?
|
a CamelSession |
Returns : |
whether or not we are checking incoming messages for 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.
|
a CamelSession |
|
whether to check incoming messages for junk |
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.
|
a CamelSession |
Returns : |
a CamelJunkFilter, or NULL
|
Since 3.2
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.
|
a CamelSession |
|
a CamelJunkFilter, or NULL
|
Since 3.2
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
.
|
a CamelSession |
|
the priority of the idle source |
|
a function to call |
|
data to pass to function
|
|
function to call when the idle is removed, or NULL
|
Returns : |
the ID (greater than 0) of the event source |
Since 3.6
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.
|
a CamelSession |
|
a CamelOperation cast as a GCancellable |
|
data passed to camel_session_submit_job()
|
|
return location for a GError |
Since 3.2
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.
|
a CamelSession |
|
a CamelSessionCallback |
|
user data passed to the callback |
|
a GDestroyNotify function |
Since 3.2
gboolean camel_session_get_network_available (CamelSession *session
);
|
a CamelSession |
Since 2.32
void camel_session_set_network_available (CamelSession *session
,gboolean network_available
);
|
a CamelSession |
|
whether a network is available |
Since 2.32
const GHashTable * camel_session_get_junk_headers (CamelSession *session
);
Since 2.22
void camel_session_set_junk_headers (CamelSession *session
,const gchar **headers
,const gchar **values
,gint len
);
Since 2.22
gboolean camel_session_lookup_addressbook (CamelSession *session
,const gchar *name
);
Since 2.22
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
.
|
a CamelSession |
|
a CamelService |
|
a SASL mechanism name, or NULL
|
|
optional GCancellable object, or NULL
|
|
return location for a GError, or NULL
|
Returns : |
TRUE on success, FALSE on failure |
Since 3.4
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.
|
a CamelSession |
|
a CamelService |
|
a SASL mechanism name, or NULL
|
|
the I/O priority for the request |
|
optional GCancellable object, or NULL
|
|
a GAsyncReadyCallback to call when the request is satisfied |
|
data to pass to the callback function |
Since 3.4
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
.
|
a CamelSession |
|
a GAsyncResult |
|
return location for a GError, or NULL
|
Returns : |
TRUE on success, FALSE on failure |
Since 3.4
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
.
|
a CamelSession |
|
the CamelFolder where message is located |
|
the CamelMimeMessage to forward |
|
the recipient's email address |
|
optional GCancellable object, or NULL
|
|
return location for a GError, or NULL
|
Returns : |
TRUE on success, FALSE on failure |
Since 3.6
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.
|
a CamelSession |
|
the CamelFolder where message is located |
|
the CamelMimeMessage to forward |
|
the recipient's email address |
|
the I/O priority for the request |
|
optional GCancellable object, or NULL
|
|
a GAsyncReadyCallback to call when the request is satisfied |
|
data to pass to the callback function |
Since 3.6
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
.
|
a CamelSession |
|
a GAsyncResult |
|
return location for a GError, or NULL
|
Returns : |
TRUE on success, FALSE on failure |
Since 3.6
GMainContext * camel_session_get_main_context (CamelSession *session
);
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.
|
a CamelSession |
Returns : |
a GMainContext |
Since 3.6
"check-junk"
property "check-junk" gboolean : Read / Write / Construct
Check incoming messages for junk.
Default value: FALSE
"junk-filter"
property"junk-filter" CamelJunkFilter* : Read / Write
Classifies messages as junk or not junk.
"main-context"
property "main-context" GMainContext* : Read
The main loop context on which to attach event sources.
"network-available"
property "network-available" gboolean : Read / Write / Construct
Whether the network is available.
Default value: TRUE
"online"
property "online" gboolean : Read / Write / Construct
Whether the shell is online.
Default value: TRUE
"user-cache-dir"
property "user-cache-dir" gchar* : Read / Write / Construct
User-specific base directory for mail cache.
Default value: NULL
"job-finished"
signalvoid user_function (CamelSession *camelsession,
GCancellable *arg1,
gpointer arg2,
gpointer user_data) : Run Last
"job-started"
signalvoid user_function (CamelSession *camelsession,
GCancellable *arg1,
gpointer user_data) : Run Last