Ocsigen

Reference manual

Version 0.99.5

Index

Lwt
Eliom
Main modules
Pages with Ocamlduce
XHTML pages typed with variants
Other pages
Creating new kinds of pages
Ocsigen

This is a preliminary version of the documentation. Help us to improve it by filling tickets. We are looking for native english speakers to proof read the documentation. Contact us!

Previous Up Next

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: 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_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_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 -> Extensions.url_path
returns the full path of the URL using the type 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 -> 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.

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_service_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_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.

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_data_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 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.

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_persistent_data_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 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

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.
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. 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 Eliomsessions.set_service_session_group.
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. 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 Eliomsessions.set_volatile_data_session_group.
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. 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 Eliomsessions.set_persistent_data_session_group.

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



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 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 : ?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 Eliomsessions.close_volatile_data_session followed by Eliomsessions.close_service_session and Eliomsessions.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 Eliomsessions.close_volatile_data_session followed by Eliomsessions.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 Eliommod.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 Eliommod.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 Eliommod.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 Eliommod.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 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.