CamelSession
3
CAMEL Library

# CamelSession

## Synopsis

    struct              CamelSession;
    gboolean            (*CamelTimeoutCallback)             (gpointer data);
    enum                CamelSessionAlertType;
                        CamelSessionThreadOps;
                        CamelSessionThreadMsg;
    void                camel_session_construct             (CamelSession *session,
                                                             const char *storage_path);
    CamelService*       camel_session_get_service           (CamelSession *session,
                                                             const char *url_string,
                                                             CamelProviderType type,
                                                             CamelException *ex);
    CamelService*       camel_session_get_service_connected (CamelSession *session,
                                                             const char *url_string,
                                                             CamelProviderType type,
                                                             CamelException *ex);
    #define             camel_session_get_store             (session, url_string, ex)
    #define             camel_session_get_transport         (session, url_string, ex)
    char*               camel_session_get_storage_path      (CamelSession *session,
                                                             CamelService *service,
                                                             CamelException *ex);
    char*               camel_session_get_password          (CamelSession *session,
                                                             CamelService *service,
                                                             const char *domain,
                                                             const char *prompt,
                                                             const char *item,
                                                             guint32 flags,
                                                             CamelException *ex);
    void                camel_session_forget_password       (CamelSession *session,
                                                             CamelService *service,
                                                             const char *domain,
                                                             const char *item,
                                                             CamelException *ex);
    gboolean            camel_session_alert_user            (CamelSession *session,
                                                             CamelSessionAlertType type,
                                                             const char *prompt,
                                                             gboolean cancel);
    char*               camel_session_build_password_prompt (const char *type,
                                                             const char *user,
                                                             const char *host);
    gboolean            camel_session_is_online             (CamelSession *session);
    void                camel_session_set_online            (CamelSession *session,
                                                             gboolean online);
    CamelFilterDriver*  camel_session_get_filter_driver     (CamelSession *session,
                                                             const char *type,
                                                             CamelException *ex);
    gboolean            camel_session_check_junk            (CamelSession *session);
    void                camel_session_set_check_junk        (CamelSession *session,
                                                             gboolean check_junk);
    void*               camel_session_thread_msg_new        (CamelSession *session,
                                                             CamelSessionThreadOps *ops,
                                                             unsigned int size);
    void                camel_session_thread_msg_free       (CamelSession *session,
                                                             CamelSessionThreadMsg *msg);
    int                 camel_session_thread_queue          (CamelSession *session,
                                                             CamelSessionThreadMsg *msg,
                                                             int flags);
    void                camel_session_thread_wait           (CamelSession *session,
                                                             int id);
    gboolean            camel_session_get_network_state     (CamelSession *session);
    void                camel_session_set_network_state     (CamelSession *session,
                                                             gboolean network_state);
    const GHashTable*   camel_session_get_junk_headers      (CamelSession *session);
    void                camel_session_set_junk_headers      (CamelSession *session,
                                                             const char **headers,
                                                             const char **values,
                                                             int len);
    gboolean            camel_session_lookup_addressbook    (CamelSession *session,
                                                             const char *name);

## Description

## Details

### struct CamelSession

    struct CamelSession {
    	CamelObject parent_object;
    	struct _CamelSessionPrivate *priv;

    	char *storage_path;
    	CamelJunkPlugin *junk_plugin;

    	guint online:1;
    	guint check_junk:1;
    	guint network_state:1;
    };

### CamelTimeoutCallback ()

    gboolean            (*CamelTimeoutCallback)             (gpointer data);

`data` :

Returns :

### enum CamelSessionAlertType

    typedef enum {
    	CAMEL_SESSION_ALERT_INFO,
    	CAMEL_SESSION_ALERT_WARNING,
    	CAMEL_SESSION_ALERT_ERROR
    } CamelSessionAlertType;

### CamelSessionThreadOps

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

### CamelSessionThreadMsg

    typedef struct {
    	EMsg msg;

    	int id;

    	CamelException ex;
    	CamelSessionThreadOps *ops;
    	struct _CamelOperation *op;
    	CamelSession *session;

    	void *data; /* free for implementation to define, not used by camel, do not use in client code */
    	/* user fields follow */
    } CamelSessionThreadMsg;

### camel_session_construct ()

    void                camel_session_construct             (CamelSession *session,
                                                             const char *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_get_service ()

    CamelService*       camel_session_get_service           (CamelSession *session,
                                                             const char *url_string,
                                                             CamelProviderType type,
                                                             CamelException *ex);

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.

`ex` :

  a CamelException

Returns :

  the requested CamelService, or `NULL`

### camel_session_get_service_connected ()

    CamelService*       camel_session_get_service_connected (CamelSession *session,
                                                             const char *url_string,
                                                             CamelProviderType type,
                                                             CamelException *ex);

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

`ex` :

  a CamelException

Returns :

  the requested CamelService, or `NULL`

### camel_session_get_store()

    #define             camel_session_get_store(session, url_string, ex)

`session` :

`url_string` :

`ex` :

### camel_session_get_transport()

    #define             camel_session_get_transport(session, url_string, ex)

`session` :

`url_string` :

`ex` :

### camel_session_get_storage_path ()

    char*               camel_session_get_storage_path      (CamelSession *session,
                                                             CamelService *service,
                                                             CamelException *ex);

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

`ex` :

  a CamelException

Returns :

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

### camel_session_get_password ()

    char*               camel_session_get_password          (CamelSession *session,
                                                             CamelService *service,
                                                             const char *domain,
                                                             const char *prompt,
                                                             const char *item,
                                                             guint32 flags,
                                                             CamelException *ex);

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 `ex` to CAMEL_EXCEPTION_USER_CANCEL 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

`ex` :

  a CamelException

Returns :

  the authentication information or `NULL`

### camel_session_forget_password ()

    void                camel_session_forget_password       (CamelSession *session,
                                                             CamelService *service,
                                                             const char *domain,
                                                             const char *item,
                                                             CamelException *ex);

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

`domain` :

`item` :

  an identifier, unique within this service, for the information

`ex` :

  a CamelException

### camel_session_alert_user ()

    gboolean            camel_session_alert_user            (CamelSession *session,
                                                             CamelSessionAlertType type,
                                                             const char *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 ()

    char*               camel_session_build_password_prompt (const char *type,
                                                             const char *user,
                                                             const char *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

### camel_session_is_online ()

    gboolean            camel_session_is_online             (CamelSession *session);

`session` :

  a CamelSession object

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 object

`online` :

  whether or not the session should be online

### camel_session_get_filter_driver ()

    CamelFilterDriver*  camel_session_get_filter_driver     (CamelSession *session,
                                                             const char *type,
                                                             CamelException *ex);

`session` :

  a CamelSession object

`type` :

  the type of filter (eg, "incoming")

`ex` :

  a CamelException

Returns :

  a filter driver, loaded with applicable rules

### camel_session_check_junk ()

    gboolean            camel_session_check_junk            (CamelSession *session);

Do we have to check incoming messages to be junk?

`session` :

  a CamelSession object

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 object

`check_junk` :

  state

### camel_session_thread_msg_new ()

    void*               camel_session_thread_msg_new        (CamelSession *session,
                                                             CamelSessionThreadOps *ops,
                                                             unsigned int 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 ()

    int                 camel_session_thread_queue          (CamelSession *session,
                                                             CamelSessionThreadMsg *msg,
                                                             int 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,
                                                             int 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_state ()

    gboolean            camel_session_get_network_state     (CamelSession *session);

`session` :

Returns :

### camel_session_set_network_state ()

    void                camel_session_set_network_state     (CamelSession *session,
                                                             gboolean network_state);

`session` :

`network_state` :

### camel_session_get_junk_headers ()

    const GHashTable*   camel_session_get_junk_headers      (CamelSession *session);

`session` :

Returns :

### camel_session_set_junk_headers ()

    void                camel_session_set_junk_headers      (CamelSession *session,
                                                             const char **headers,
                                                             const char **values,
                                                             int len);

`session` :

`headers` :

`values` :

`len` :

### camel_session_lookup_addressbook ()

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

`session` :

`name` :

Returns :