CamelSession

CamelSession

Synopsis

struct              CamelSession;
gboolean            (*CamelTimeoutCallback)             (gpointer data);
enum                CamelSessionAlertType;
struct              CamelSessionThreadOps;
struct              CamelSessionThreadMsg;
void                camel_session_construct             (CamelSession *session,
                                                         const gchar *storage_path);
void                camel_session_set_socks_proxy       (CamelSession *session,
                                                         const gchar *socks_host,
                                                         gint socks_port);
void                camel_session_get_socks_proxy       (CamelSession *session,
                                                         gchar **host_ret,
                                                         gint *port_ret);
CamelService *	     camel_session_get_service           (CamelSession *session,
                                                         const gchar *url_string,
                                                         CamelProviderType type,
                                                         GError **error);
CamelService *      camel_session_get_service_connected (CamelSession *session,
                                                         const gchar *url_string,
                                                         CamelProviderType type,
                                                         GError **error);
#define             camel_session_get_store             (session,
                                                         url_string,
                                                         error)
#define             camel_session_get_transport         (session,
                                                         url_string,
                                                         error)
gchar *		           camel_session_get_storage_path      (CamelSession *session,
                                                         CamelService *service,
                                                         GError **error);
gchar *		           camel_session_get_password          (CamelSession *session,
                                                         CamelService *service,
                                                         const gchar *domain,
                                                         const gchar *prompt,
                                                         const gchar *item,
                                                         guint32 flags,
                                                         GError **error);
gboolean            camel_session_forget_password       (CamelSession *session,
                                                         CamelService *service,
                                                         const gchar *domain,
                                                         const gchar *item,
                                                         GError **error);
gboolean            camel_session_alert_user            (CamelSession *session,
                                                         CamelSessionAlertType type,
                                                         const gchar *prompt,
                                                         gboolean cancel);
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);
gpointer            camel_session_thread_msg_new        (CamelSession *session,
                                                         CamelSessionThreadOps *ops,
                                                         guint size);
void                camel_session_thread_msg_free       (CamelSession *session,
                                                         CamelSessionThreadMsg *msg);
gint                camel_session_thread_queue          (CamelSession *session,
                                                         CamelSessionThreadMsg *msg,
                                                         gint flags);
void                camel_session_thread_wait           (CamelSession *session,
                                                         gint id);
gboolean            camel_session_get_network_available (CamelSession *session);
void                camel_session_set_network_available (CamelSession *session,
                                                         gboolean network_state);
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_forward_to            (CamelSession *session,
                                                         CamelFolder *folder,
                                                         CamelMimeMessage *message,
                                                         const gchar *address,
                                                         GError **error);
enum                CamelSessionLock;
void                camel_session_lock                  (CamelSession *session,
                                                         CamelSessionLock lock);
void                camel_session_unlock                (CamelSession *session,
                                                         CamelSessionLock lock);

Object Hierarchy

  GObject
   +----CamelObject
         +----CamelSession

Properties

  "check-junk"               gboolean              : Read / Write / Construct
  "network-available"        gboolean              : Read / Write / Construct
  "online"                   gboolean              : Read / Write / Construct

Description

Details

struct CamelSession

struct CamelSession;


CamelTimeoutCallback ()

gboolean            (*CamelTimeoutCallback)             (gpointer data);


enum CamelSessionAlertType

typedef enum {
	CAMEL_SESSION_ALERT_INFO,
	CAMEL_SESSION_ALERT_WARNING,
	CAMEL_SESSION_ALERT_ERROR
} CamelSessionAlertType;


struct CamelSessionThreadOps

struct CamelSessionThreadOps {
	void (*receive)(CamelSession *session, CamelSessionThreadMsg *m);
	void (*free)(CamelSession *session, CamelSessionThreadMsg *m);
};


struct CamelSessionThreadMsg

struct CamelSessionThreadMsg {
	CamelMsg msg;

	gint id;

	GError *error;
	CamelSessionThreadOps *ops;
	CamelOperation *op;
	CamelSession *session;

	gpointer data; /* Free for implementation to define, not
			 * used by Camel, do not use in client code. */

	/* user fields follow */
};


camel_session_construct ()

void                camel_session_construct             (CamelSession *session,
                                                         const gchar *storage_path);

Constructs session.

session :

a CamelSession object to construct

storage_path :

path to a directory the session can use for persistent storage. (This directory must already exist.)

camel_session_set_socks_proxy ()

void                camel_session_set_socks_proxy       (CamelSession *session,
                                                         const gchar *socks_host,
                                                         gint socks_port);

Sets a SOCKS proxy that will be used throughout the session for TCP connections.

session :

A CamelSession

socks_host :

Hostname of the SOCKS proxy, or NULL for none.

socks_port :

Port number of the SOCKS proxy

Since 2.32


camel_session_get_socks_proxy ()

void                camel_session_get_socks_proxy       (CamelSession *session,
                                                         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.

session :

A CamelSession

host_ret :

Location to return the SOCKS proxy hostname

port_ret :

Location to return the SOCKS proxy port

Since 2.32


camel_session_get_service ()

CamelService *	     camel_session_get_service           (CamelSession *session,
                                                         const gchar *url_string,
                                                         CamelProviderType type,
                                                         GError **error);

This resolves a CamelURL into a CamelService, including loading the provider library for that service if it has not already been loaded.

Services are cached, and asking for "the same" url_string multiple times will return the same CamelService (with its reference count incremented by one each time). What constitutes "the same" URL depends in part on the provider.

session :

a CamelSession object

url_string :

a CamelURL describing the service to get

type :

the provider type (CAMEL_PROVIDER_STORE or CAMEL_PROVIDER_TRANSPORT) to get, since some URLs may be able to specify either type.

error :

return location for a GError, or NULL

Returns :

the requested CamelService, or NULL

camel_session_get_service_connected ()

CamelService *      camel_session_get_service_connected (CamelSession *session,
                                                         const gchar *url_string,
                                                         CamelProviderType type,
                                                         GError **error);

This works like camel_session_get_service, but also ensures that the returned service will have been successfully connected (via camel_service_connect.)

session :

a CamelSession object

url_string :

a CamelURL describing the service to get

type :

the provider type

error :

return location for a GError, or NULL

Returns :

the requested CamelService, or NULL

camel_session_get_store()

#define             camel_session_get_store(session, url_string, error)


camel_session_get_transport()

#define             camel_session_get_transport(session, url_string, error)


camel_session_get_storage_path ()

gchar *		           camel_session_get_storage_path      (CamelSession *session,
                                                         CamelService *service,
                                                         GError **error);

This returns the path to a directory which the service can use for its own purposes. Data stored there will remain between Evolution sessions. No code outside of that service should ever touch the files in this directory. If the directory does not exist, it will be created.

session :

a CamelSession object

service :

a CamelService

error :

return location for a GError, or NULL

Returns :

the path (which the caller must free), or NULL if an error occurs.

camel_session_get_password ()

gchar *		           camel_session_get_password          (CamelSession *session,
                                                         CamelService *service,
                                                         const gchar *domain,
                                                         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 object

service :

the CamelService this query is being made by

domain :

domain of password request. May be null to use the default.

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 *domain,
                                                         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 object

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

gboolean            camel_session_alert_user            (CamelSession *session,
                                                         CamelSessionAlertType type,
                                                         const gchar *prompt,
                                                         gboolean cancel);

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 object

type :

the type of alert (info, warning, or error)

prompt :

the message for the user

cancel :

whether or not to provide a "Cancel" option in addition to an "OK" option.

Returns :

TRUE if the user accepts, FALSE if they cancel.

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 object

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

gpointer            camel_session_thread_msg_new        (CamelSession *session,
                                                         CamelSessionThreadOps *ops,
                                                         guint size);

Create a new thread message, using ops as the receive/reply/free ops, of size bytes.

ops points to the operations used to recieve/process and finally free the message.

session :

a CamelSession object

ops :

thread operations

size :

number of bytes

Returns :

a new CamelSessionThreadMsg

camel_session_thread_msg_free ()

void                camel_session_thread_msg_free       (CamelSession *session,
                                                         CamelSessionThreadMsg *msg);

Free a msg. Note that the message must have been allocated using msg_new, and must nto have been submitted to any queue function.

session :

a CamelSession object

msg :

a CamelSessionThreadMsg

camel_session_thread_queue ()

gint                camel_session_thread_queue          (CamelSession *session,
                                                         CamelSessionThreadMsg *msg,
                                                         gint flags);

Queue a thread message in another thread for processing. The operation should be (but needn't) run in a queued manner with other operations queued in this manner.

session :

a CamelSession object

msg :

a CamelSessionThreadMsg

flags :

queue type flags, currently 0.

Returns :

the id of the operation queued

camel_session_thread_wait ()

void                camel_session_thread_wait           (CamelSession *session,
                                                         gint id);

Wait on an operation to complete (by id).

session :

a CamelSession object

id :

id of the operation to wait on

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

session :

a CamelSession

Since 2.32


camel_session_get_junk_headers ()

const GHashTable *  camel_session_get_junk_headers      (CamelSession *session);

Since 2.22


camel_session_set_junk_headers ()

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

Since 2.22


camel_session_lookup_addressbook ()

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

Since 2.22


camel_session_forward_to ()

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

Since 2.26


enum CamelSessionLock

typedef enum {
	CAMEL_SESSION_SESSION_LOCK,
	CAMEL_SESSION_THREAD_LOCK
} CamelSessionLock;

Since 2.32


camel_session_lock ()

void                camel_session_lock                  (CamelSession *session,
                                                         CamelSessionLock lock);

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

session :

a CamelSession

lock :

lock type to lock

Since 2.32


camel_session_unlock ()

void                camel_session_unlock                (CamelSession *session,
                                                         CamelSessionLock lock);

Unlocks session's lock, previously locked with camel_session_lock().

session :

a CamelSession

lock :

lock type to unlock

Since 2.32

Property Details

The "check-junk" property

  "check-junk"               gboolean              : Read / Write / Construct

Check incoming messages for junk.

Default value: FALSE


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