Module Eliomsessions

module Eliomsessions: 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.

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.

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_ip : sp:server_params -> string

returns the internet address of the client as a string

val get_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_path_string : sp:server_params -> string

returns the path of the URL as a string

val get_current_full_path : sp:server_params -> Extensions.url_path

returns the full path of the URL using the type Extensions.url_path

val get_current_sub_path : sp:server_params -> Extensions.url_path

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

val get_hostname : sp:server_params -> string option

returns the hostname that has been sent by the user agent, if any. This is usefull if your server has several hostnames, but that piece of information is not mandatory for HTTP/1.0.

val get_port : sp:server_params -> int

returns the port on which the request has been done.

val get_suffix : sp:server_params -> Extensions.url_path

returns the suffix of the current URL

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

returns the cookies sent by the browser

Getting and setting information about the current session

Global configuration of session timeouts

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

sets the timeout for volatile (= "in memory") sessions (both service session and volatile data session) (server side). The sessions will be closed after this amount of time of inactivity from the user. None = 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. Sessions whose timeout has been set individually with Eliomsessions.set_volatile_session_timeout won't be affected.

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

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

sets the timeout for service sessions (server side). The sessions will be closed after this amount of time of inactivity from the user. None = no timeout.

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

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

sets the timeout for volatile (= "in memory") data sessions (server side). The sessions will be closed after this amount of time of inactivity from the user. None = no timeout.

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

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

returns the timeout for service sessions (server side). None = no timeout.

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

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). None = no timeout.

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

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 set_global_persistent_data_session_timeout : ?session_name:string ->
       ?sp:server_params ->
       ?recompute_expdates:bool -> float option -> unit Lwt.t

sets the timeout for persistent sessions (server side). The sessions will be closed after this amount of time of inactivity from the user. None = no timeout.

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

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

returns the timeout for persistent sessions (server side). None = no timeout.

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

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.

Personalizing session timeouts

val set_service_session_timeout : ?session_name:string ->
       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 -> 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 ->
       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 ->
       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 -> 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 ->
       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 ->
       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 -> 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 ->
       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 -> 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 ->
       sp:server_params -> unit -> float option Lwt.t

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

Cookies

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

Ask the browser to set the cookie expiration date for the current volatile sessions (service and data), in seconds, since the 1st of january 1970.

None means the cookie will expire when the browser is closed. No means to set cookies for an infinite time on browsers.

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

Ask the browser to set the cookie expiration date for the current service session, in seconds, since the 1st of january 1970.

None means the cookie will expire when the browser is closed. No means to set cookies for an infinite time on browsers.

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

Ask the browser to set the cookie expiration date for the current data session, in seconds, since the 1st of january 1970.

None means the cookie will expire when the browser is closed. No means to set cookies for an infinite time on browsers.

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

sets the cookie expiration date for the persistent session, in seconds, since the 1st of january 1970.

None means the cookie will expire when the browser is closed. No means to set cookies for an infinite time on browsers.

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 : Extensions.file_info -> string

returns the filename used by Ocsigen for the uploaded file.

val get_filesize : Extensions.file_info -> int64

returns the size of the file.

val get_original_filename : 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 Eliommod.Eliom_function_forbidden_outside_site_loading.

val get_site_dir : sp:server_params -> 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

type 'a session_data =

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

Session data in memory

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 Eliommod.Eliom_function_forbidden_outside_site_loading.

val get_volatile_session_data : ?session_name:string ->
       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 ->
       table:'a volatile_table ->
       sp:server_params -> 'a -> unit

sets session data for the current session.

val remove_volatile_session_data : ?session_name:string ->
       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 ->
       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 ->
       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 ->
       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 : ?session_name:string -> sp:server_params -> unit -> unit Lwt.t

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

Shortcut for Eliomsessions.close_volatile_data_session followed by Eliomsessions.close_service_session and Eliomsessions.close_persistent_data_session.

val close_volatile_session : ?session_name:string -> 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 Eliomsessions.close_volatile_data_session followed by Eliomsessions.close_service_session.

val close_persistent_data_session : ?session_name:string -> 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 : ?session_name:string -> sp:server_params -> unit -> unit

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

val close_service_session : ?session_name:string -> sp:server_params -> unit -> unit

Close Eliom's current service session, if opened

Administrating sessions

val close_all_sessions : ?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 Eliommod.Eliom_function_forbidden_outside_site_loading.

val close_all_volatile_sessions : ?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 Eliommod.Eliom_function_forbidden_outside_site_loading.

val close_all_persistent_data_sessions : ?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 Eliommod.Eliom_function_forbidden_outside_site_loading.

val close_all_service_sessions : ?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 Eliommod.Eliom_function_forbidden_outside_site_loading.

val close_all_volatile_data_sessions : ?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 Eliommod.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_get_params : sp:server_params -> (string * string) list

returns all parameters of the URL (GET parameters) (even those that are for another service)

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)

Other low level functions

You probably don't need these functions.

val get_ri : sp:server_params -> 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 ->
       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 ->
       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 ->
       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.