# Module Eliom_sessions

    module Eliom_sessions: sig .. end

This module contains the functions you need to get (or set) information about the request or the session.

There are three kinds of sessions, all using different cookies:

- service sessions (used to register services in a table of session),
- volatile data sessions (used to save session data in tables in memory),
- persistent sessions (used to save session data on hard disk).

For all these sessions, you may set a timeout (global or individual for one user) or set an expiration date for the cookie. "Volatile" denotes both service and in memory data sessions.

Be very carefull if you use several sessions concurrently, as they may have different duration (one may be closed while the other are not). Duration of service sessions is sometimes shorter than volatile data sessions, which is usually shorter than persistent sessions.

If you want several sessions of the same type for one site, you can choose a personalized session name by giving the optional parameter `?session_name`.

It is highly recommended to put all the sessions for one user in one session group. Thus, it will be possible to implement features like "close all opened sessions" for one user, or limitation of the number of sessions one user can open concurrently, or setting data for one group of sessions.

## Getting information about the request

    type server_params

    val get_user_agent : sp:server_params -> string

returns the name of the user agent that did the request (usually the name of the browser).

    val get_full_url : sp:server_params -> string

returns the full URL as a string

    val get_remote_ip : sp:server_params -> string

returns the internet address of the client as a string

    val get_remote_inet_addr : sp:server_params -> Unix.inet_addr

returns the internet address of the client, using the type `Unix.inet_addr` (defined in OCaml's standard library).

    val get_current_full_path_string : sp:server_params -> string

returns the full path of the URL as a string.

    val get_current_full_path : sp:server_params -> Ocsigen_extensions.url_path

returns the full path of the URL using the type `Ocsigen_extensions.url_path`

    val get_current_sub_path_string : sp:server_params -> string

returns the sub path of the URL as a string. The sub-path is the full path without the path of the site (set in the configuration file).

    val get_current_sub_path : sp:server_params -> Ocsigen_extensions.url_path

returns the sub path of the URL using the type `Ocsigen_extensions.url_path`. The sub-path is the full path without the path of the site (set in the configuration file).

    val get_header_hostname : sp:server_params -> string option

returns the hostname that has been sent by the user agent. For HTTP/1.0, the Host field is not mandatory in the request.

    val get_hostname : sp:server_params -> string

returns the hostname declared in the config file (`<host defaulthostname="...">`).

    val get_default_port : sp:server_params -> int

returns the port number declared in the config file (`<host defaulthttpport="...">`).

    val get_default_sslport : sp:server_params -> int

returns the https port number declared in the config file (`<host defaulthttpsport="...">`).

    val get_server_port : sp:server_params -> int

returns the port on which the request has been done.

    val get_ssl : sp:server_params -> bool

returns true if https is used, false if http.

    val get_suffix : sp:server_params -> Ocsigen_extensions.url_path

returns the suffix of the current URL

    val get_cookies : sp:server_params -> string Ocsigen_http_frame.Cookievalues.t

returns the cookies sent by the browser

## Getting and setting information about the current session

### Global configuration of session timeouts

The following functions set the timeout for sessions, for the different kinds of session. The sessions will be closed after this amount of time of inactivity from the user. `None` means no timeout.

The optional parameter `?recompute_expdates` is `false` by default. If you set it to `true`, the expiration dates for all sessions in the table will be recomputed with the new timeout. That is, the difference between the new timeout and the old one will be added to their expiration dates (by another Lwt thread). Sessions whose timeout has been set individually with `Eliom_sessions.set_volatile_session_timeout` won't be affected.

Warning: If you use one of these functions after the initialisation phase, you must give the `~sp` parameter, otherwise it will raise the exception `Eliom_common.Eliom_function_forbidden_outside_site_loading`. This remark also applies to `get_*` functions.

    val set_global_volatile_session_timeout : ?session_name:string ->
           ?sp:server_params ->
           ?recompute_expdates:bool -> float option -> unit

Sets the timeout for volatile (= "in memory") sessions (both service session and volatile data session) (server side).

    val set_global_service_session_timeout : ?session_name:string ->
           ?sp:server_params ->
           ?recompute_expdates:bool -> float option -> unit

Sets the timeout for service sessions (server side).

    val set_global_volatile_data_session_timeout : ?session_name:string ->
           ?sp:server_params ->
           ?recompute_expdates:bool -> float option -> unit

Sets the timeout for volatile (= "in memory") data sessions (server side).

    val set_global_persistent_data_session_timeout : ?session_name:string ->
           ?sp:server_params ->
           ?recompute_expdates:bool -> float option -> unit

Sets the timeout for persistent sessions (server side).

    val get_global_service_session_timeout : ?session_name:string ->
           ?sp:server_params -> unit -> float option

Returns the timeout for service sessions (server side).

    val get_global_volatile_data_session_timeout : ?session_name:string ->
           ?sp:server_params -> unit -> float option

Returns the timeout for "volatile data" sessions (server side).

    val get_global_persistent_data_session_timeout : ?session_name:string ->
           ?sp:server_params -> unit -> float option

Returns the timeout for persistent sessions (server side).

### Personalizing session timeouts

    val set_service_session_timeout : ?session_name:string ->
           ?secure:bool -> sp:server_params -> float option -> unit

sets the timeout for service session (server side) for one user, in seconds. `None` = no timeout

    val unset_service_session_timeout : ?session_name:string ->
           ?secure:bool -> sp:server_params -> unit -> unit

remove the service session timeout for one user (and turn back to the default).

    val get_service_session_timeout : ?session_name:string ->
           ?secure:bool -> sp:server_params -> unit -> float option

returns the timeout for current service session. `None` = no timeout

    val set_volatile_data_session_timeout : ?session_name:string ->
           ?secure:bool -> sp:server_params -> float option -> unit

sets the timeout for volatile data session (server side) for one user, in seconds. `None` = no timeout

    val unset_volatile_data_session_timeout : ?session_name:string ->
           ?secure:bool -> sp:server_params -> unit -> unit

remove the "volatile data" session timeout for one user (and turn back to the default).

    val get_volatile_data_session_timeout : ?session_name:string ->
           ?secure:bool -> sp:server_params -> unit -> float option

returns the timeout for current volatile data session. `None` = no timeout

    val set_volatile_session_timeout : ?session_name:string ->
           ?secure:bool -> sp:server_params -> float option -> unit

sets the timeout for volatile sessions (service and volatile data) (server side) for one user, in seconds. `None` = no timeout

    val unset_volatile_session_timeout : ?session_name:string ->
           ?secure:bool -> sp:server_params -> unit -> unit

remove the session timeout for one user for both service session and volatile data session (and turn back to the default).

    val set_persistent_data_session_timeout : ?session_name:string ->
           ?secure:bool -> sp:server_params -> float option -> unit Lwt.t

sets the timeout for persistent session (server side) for one user, in seconds. `None` = no timeout

    val unset_persistent_data_session_timeout : ?session_name:string ->
           ?secure:bool -> sp:server_params -> unit -> unit Lwt.t

remove the persistent session timeout for one user (and turn back to the default).

    val get_persistent_data_session_timeout : ?session_name:string ->
           ?secure:bool -> sp:server_params -> unit -> float option Lwt.t

returns the persistent session timeout for one user. `None` = no timeout

### Session groups

`type `'a` session_data =`

`|` | `No_data`
`|` | `Data_session_expired`
`|` | `Data of `'a``

Session groups may be used for example to limit the number of sessions one user can open at the same time, or to implement a "close all sessions" feature. Usually, the group is the user name.

    val set_service_session_group : ?set_max:int option ->
           ?session_name:string ->
           ?secure:bool -> sp:server_params -> string -> unit

sets the group to which belong the service session. If the optional `?set_max` parameter is present, also sets the maximum number of sessions in the group. `None` means "no limitation". If `~secure` is false when the protocol is https, it will affect the unsecure session, otherwise, il will affect the secure session in https, the unsecure one in http.

    val unset_service_session_group : ?session_name:string ->
           ?secure:bool -> sp:server_params -> unit -> unit

Remove the session from its group

    val get_service_session_group : ?session_name:string ->
           ?secure:bool ->
           sp:server_params -> unit -> string session_data

returns the group to which belong the service session. If the session does not belong to any group, or if no session is opened, return `None`.

    val set_volatile_data_session_group : ?set_max:int option ->
           ?session_name:string ->
           ?secure:bool -> sp:server_params -> string -> unit

sets the group to which belong the volatile data session. If the optional `?set_max` parameter is present, also sets the maximum number of sessions in the group. `None` means "no limitation".

    val unset_volatile_data_session_group : ?session_name:string ->
           ?secure:bool -> sp:server_params -> unit -> unit

Remove the session from its group

    val get_volatile_data_session_group : ?session_name:string ->
           ?secure:bool ->
           sp:server_params -> unit -> string session_data

returns the group to which belong the data session. If the session does not belong to any group, or if no session is opened, return `None`.

    val set_persistent_data_session_group : ?set_max:int option ->
           ?session_name:string ->
           ?secure:bool -> sp:server_params -> string -> unit Lwt.t

sets the group to which belong the persistent session. If the optional `?set_max` parameter is present, also sets the maximum number of sessions in the group. `None` means "no limitation".

    val unset_persistent_data_session_group : ?session_name:string ->
           ?secure:bool -> sp:server_params -> unit -> unit Lwt.t

Remove the session from its group

    val get_persistent_data_session_group : ?session_name:string ->
           ?secure:bool ->
           sp:server_params ->
           unit -> string session_data Lwt.t

returns the group to which belong the persistent session. If the session does not belong to any group, or if no session is opened, return `None`.
The following functions of this section set the maximum number of sessions in a session group, for the different kinds of session. `None` means "no limit". This won't modify existing groups. That value will be used only as default value if you do not specify the optional parameter `?set_max` of function `Eliom_sessions.set_volatile_data_session_group`.

    val set_default_max_service_sessions_per_group : sp:server_params -> int option -> unit

Sets the maximum number of service sessions in a session group (see above).

    val set_default_max_volatile_data_sessions_per_group : sp:server_params -> int option -> unit

Sets the maximum number of volatile data sessions in a session group (see above).

    val set_default_max_persistent_data_sessions_per_group : sp:server_params -> int option -> unit

Sets the maximum number of persistent data sessions in a session group (see above).

### Cookies

The functions in this section ask the browser to set the cookie expiration date, for the different kinds of session, in seconds, since the 1st of January 1970. `None` means the cookie will expire when the browser is closed. Note: there is no way to set cookies for an infinite time on browsers.

    val set_volatile_session_cookies_exp_date : ?session_name:string ->
           ?secure:bool -> sp:server_params -> float option -> unit

Sets the cookie expiration date for the current volatile sessions (service and data) (see above).

    val set_service_session_cookie_exp_date : ?session_name:string ->
           ?secure:bool -> sp:server_params -> float option -> unit

Sets the cookie expiration date for the current service session (see above).

    val set_volatile_data_session_cookie_exp_date : ?session_name:string ->
           ?secure:bool -> sp:server_params -> float option -> unit

Sets the cookie expiration date for the current data session (see above).

    val set_persistent_data_session_cookie_exp_date : ?session_name:string ->
           ?secure:bool -> sp:server_params -> float option -> unit Lwt.t

Sets the cookie expiration date for the persistent session (see above).

### Exceptions and fallbacks

    val get_exn : sp:server_params -> exn list

returns the exceptions that have been sent by the previous services to their fallback, if any. Keep an eye on these exception to know what succeeded before that service was called (failed connection, timeout ...)

    val get_previous_extension_error_code : sp:server_params -> int

returns the HTTP error code sent by the Ocsigen extension that tried to answer to the request before Eliom. It is 404 by default.

## Getting information about files uploaded

Warning: The files uploaded are automatically erased by Ocsigen just after the request has been fulfilled. If you want to keep them, create a new hard link yourself during the service (or make a copy).

    val get_tmp_filename : Ocsigen_extensions.file_info -> string

returns the filename used by Ocsigen for the uploaded file.

    val get_filesize : Ocsigen_extensions.file_info -> int64

returns the size of the file.

    val get_original_filename : Ocsigen_extensions.file_info -> string

returns the name the file had on the client when it has been sent.

## Getting information from the configuration file

    val get_config : unit -> Simplexmlparser.xml list

returns the information of the configuration file concerning that site (between `<site>` and `</site>`).

Warning: You must call that function during the initialisation of your module (not during a Lwt thread or a service). If you use that function after, you must give the `~sp` parameter, otherwise it will raise the exception `Eliom_common.Eliom_function_forbidden_outside_site_loading`.

    val get_site_dir : sp:server_params -> Ocsigen_extensions.url_path

returns the root of the site.

    val get_config_file_charset : sp:server_params -> string

returns the charset for this site (from the configuration file)

## Session data

### In memory session data

    type 'a volatile_table

The type of (volatile) session data tables.

    val create_volatile_table : ?sp:server_params -> unit -> 'a volatile_table

creates a table in memory where you can store the session data for all users.

Warning: If you use that function after the initialization phase, you must give the `~sp` parameter, otherwise it will raise the exception `Eliom_common.Eliom_function_forbidden_outside_site_loading`.

    val get_volatile_session_data : ?session_name:string ->
           ?secure:bool ->
           table:'a volatile_table ->
           sp:server_params -> unit -> 'a session_data

gets session data for the current session (if any).

    val set_volatile_session_data : ?session_name:string ->
           ?secure:bool ->
           table:'a volatile_table ->
           sp:server_params -> 'a -> unit

sets session data for the current session.

    val remove_volatile_session_data : ?session_name:string ->
           ?secure:bool ->
           table:'a volatile_table ->
           sp:server_params -> unit -> unit

removes session data for the current session (but does not close the session). If the session does not exist, do nothing.

### Persistent sessions

    type 'a persistent_table

The type of persistent session data tables.

    val create_persistent_table : string -> 'a persistent_table

creates a table on hard disk where you can store the session data for all users. It uses `Ocsipersist`.

    val get_persistent_session_data : ?session_name:string ->
           ?secure:bool ->
           table:'a persistent_table ->
           sp:server_params ->
           unit -> 'a session_data Lwt.t

gets persistent session data for the current persistent session (if any)

    val set_persistent_session_data : ?session_name:string ->
           ?secure:bool ->
           table:'a persistent_table ->
           sp:server_params -> 'a -> unit Lwt.t

sets persistent session data for the current persistent session

    val remove_persistent_session_data : ?session_name:string ->
           ?secure:bool ->
           table:'a persistent_table ->
           sp:server_params -> unit -> unit Lwt.t

removes session data for the current persistent session (but does not close the session). If the session does not exist, do nothing.

## Closing sessions

    val close_session : ?close_group:bool ->
           ?session_name:string ->
           ?secure:bool -> sp:server_params -> unit -> unit Lwt.t

Close Eliom's current sessions if opened (service session, volatile data session and persistent session).

Shortcut for `Eliom_sessions.close_volatile_data_session` followed by `Eliom_sessions.close_service_session` and `Eliom_sessions.close_persistent_data_session`.

By default will close both secure and unsecure sessions, but if `~secure` is present.

    val close_volatile_session : ?close_group:bool ->
           ?session_name:string ->
           ?secure:bool -> sp:server_params -> unit -> unit

Close Eliom's current volatile session if opened (both service session and volatile data session) (destroying all session data for that user).

Shortcut for `Eliom_sessions.close_volatile_data_session` followed by `Eliom_sessions.close_service_session`.

    val close_persistent_data_session : ?close_group:bool ->
           ?session_name:string ->
           ?secure:bool -> sp:server_params -> unit -> unit Lwt.t

Close Eliom's current persistent session if opened (destroying all persistent data for that user)

    val close_volatile_data_session : ?close_group:bool ->
           ?session_name:string ->
           ?secure:bool -> sp:server_params -> unit -> unit

Close Eliom's current data session, if opened (destroying all session data for that user)

    val close_service_session : ?close_group:bool ->
           ?session_name:string ->
           ?secure:bool -> sp:server_params -> unit -> unit

Close Eliom's current service session, if opened

## Administrating sessions

    val close_all_sessions : ?close_group:bool ->
           ?session_name:string ->
           ?sp:server_params -> unit -> unit Lwt.t

Close all persistent and volatile sessions for one session name. If the optional parameter `?session_name` (session name) is not present, the session with default name is closed.

Warning: If you use this function after the initialisation phase, you must give the `~sp` parameter, otherwise it will raise the exception `Eliom_common.Eliom_function_forbidden_outside_site_loading`.

    val close_all_volatile_sessions : ?close_group:bool ->
           ?session_name:string ->
           ?sp:server_params -> unit -> unit Lwt.t

Close all volatile (service and volatile data) sessions for one session name. If the optional parameter `?session_name` (session name) is not present, the session with default name is closed.

Warning: If you use this function after the initialisation phase, you must give the `~sp` parameter, otherwise it will raise the exception `Eliom_common.Eliom_function_forbidden_outside_site_loading`.

    val close_all_persistent_data_sessions : ?close_group:bool ->
           ?session_name:string ->
           ?sp:server_params -> unit -> unit Lwt.t

Close all persistent sessions for one session name. If the optional parameter `?session_name` (session name) is not present, the session with default name is closed.

Warning: If you use this function after the initialisation phase, you must give the `~sp` parameter, otherwise it will raise the exception `Eliom_common.Eliom_function_forbidden_outside_site_loading`.

    val close_all_service_sessions : ?close_group:bool ->
           ?session_name:string ->
           ?sp:server_params -> unit -> unit Lwt.t

Close all service sessions for one session name. If the optional parameter `?session_name` (session name) is not present, the session with default name is closed.

Warning: If you use this function after the initialisation phase, you must give the `~sp` parameter, otherwise it will raise the exception `Eliom_common.Eliom_function_forbidden_outside_site_loading`.

    val close_all_volatile_data_sessions : ?close_group:bool ->
           ?session_name:string ->
           ?sp:server_params -> unit -> unit Lwt.t

Close all volatile data sessions for one session name. If the optional parameter `?session_name` (session name) is not present, the session with default name is closed.

Warning: If you use this function after the initialisation phase, you must give the `~sp` parameter, otherwise it will raise the exception `Eliom_common.Eliom_function_forbidden_outside_site_loading`.

    module Session_admin: sig .. end

## Getting parameters (low level)

The usual way to get parameters with Eliom is to use the second and third parameters of the service handlers. These are low level functions you may need for more advanced use.

    val get_get_params : sp:server_params -> (string * string) list

returns the parameters of the URL (GET parameters) that concern the running service. For example in the case of a non-attached coservice called from a page with GET parameters, only the parameters of that non-attached coservice are returned (even if the other are still in the URL).

    val get_all_current_get_params : sp:server_params -> (string * string) list

returns current parameters of the URL (GET parameters) (even those that are for subsequent services, but not previous actions)

    val get_initial_get_params : sp:server_params -> (string * string) list

returns all parameters of the URL (GET parameters) as sent initially by the browser

    val get_other_get_params : sp:server_params -> (string * string) list

returns the parameters of the URL (GET parameters) that do not concern the running service.

    val get_post_params : sp:server_params -> (string * string) list Lwt.t

returns the parameters in the body of the HTTP request (POST parameters) that concern the running service

    val get_all_post_params : sp:server_params -> (string * string) list

returns all parameters in the body of the HTTP request (POST parameters) (even those that are for another service)

## Default timeouts

    val get_default_service_session_timeout : unit -> float option

returns the default timeout for service sessions (server side). The default timeout is common for all sessions for which no other value has been set. At the beginning of the server, it is taken from the configuration file, (or set to default value). `None` = no timeout.

    val get_default_volatile_data_session_timeout : unit -> float option

returns the default timeout for "volatile data" sessions (server side). The default timeout is common for all sessions for which no other value has been set. At the beginning of the server, it is taken from the configuration file, (or set to default value). `None` = no timeout.

    val set_default_volatile_session_timeout : float option -> unit

sets the default timeout for volatile (= "in memory") sessions (i.e. both service session and volatile data session) (server side). `None` = no timeout.

    val set_default_service_session_timeout : float option -> unit

sets the default timeout for service sessions. `None` = no timeout.

    val set_default_volatile_data_session_timeout : float option -> unit

sets the default timeout for "volatile data" sessions (server side). `None` = no timeout.

    val get_default_persistent_data_session_timeout : unit -> float option

returns the default timeout for sessions (server side). The default timeout is common for all sessions for which no other value has been set. At the beginning of the server, it is taken from the configuration file, (or set to default value). `None` = no timeout.

    val set_default_persistent_data_session_timeout : float option -> unit

sets the default timeout for sessions (server side). `None` = no timeout.

## Other low level functions

You probably don't need these functions.

    val get_ri : sp:server_params -> Ocsigen_extensions.request_info

returns all the information about the request.

    val get_session_name : sp:server_params -> string option

returns the name of the sessions to which belongs the running service (`None` if it is not a session service)

    val get_persistent_data_session_cookie : ?session_name:string ->
           ?secure:bool ->
           sp:server_params -> unit -> string option Lwt.t

returns the value of the Eliom's cookies for one persistent session. Returns `None` is no session is active.

    val get_service_session_cookie : ?session_name:string ->
           ?secure:bool -> sp:server_params -> unit -> string option

returns the value of Eliom's cookies for one service session. Returns `None` is no session is active.

    val get_volatile_data_session_cookie : ?session_name:string ->
           ?secure:bool -> sp:server_params -> unit -> string option

returns the value of Eliom's cookies for one "volatile data" session. Returns `None` is no session is active.