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_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_server_port : sp:server_params -> int
returns the port on which the request has been done.
val get_server_inet_addr : sp:server_params -> Unix.inet_addr
returns the inet address 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 ->
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
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 -> 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".
val unset_service_session_group : ?session_name:string -> sp:server_params -> unit -> unit
Remove the session from its group
val get_service_session_group :
?session_name:string ->
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 -> 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 -> sp:server_params -> unit -> unit
Remove the session from its group
val get_volatile_data_session_group :
?session_name:string ->
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 ->
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 -> sp:server_params -> unit -> unit Lwt.t
Remove the session from its group
val get_persistent_data_session_group :
?session_name:string ->
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 ->
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 ->
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 ->
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 ->
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 ->
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 :
?close_group:bool ->
?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 Eliom_sessions.close_volatile_data_session followed by
Eliom_sessions.close_service_session and
Eliom_sessions.close_persistent_data_session.
val close_volatile_session :
?close_group:bool ->
?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 Eliom_sessions.close_volatile_data_session followed by
Eliom_sessions.close_service_session.
val close_persistent_data_session :
?close_group:bool ->
?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 :
?close_group:bool ->
?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 :
?close_group:bool ->
?session_name:string -> 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_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)
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 ->
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.