NAME

       Eliom_service - Creation and manipulation of Eliom services.

Module

       Module   Eliom_service

Documentation

       Module Eliom_service
        : sig end

       Creation and manipulation of Eliom services.

       See the Eliom manual for a detailed introduction to the concept of .

       === Type definitions for services ===

       === Services kind ===

       === Internal or external ===

       type servcoserv = [ `Coservice | `Service ]

       An internal attached service could either be a `Service or a `Coservice .

       type attached_service_kind = [ `External | `Internal of servcoserv ]

       An  attached  service  could  either  be  an  `Internal  Eliom service or an abstraction for an `External
       service.

       === POST or GET parameters ===

       type getpost = [ `Get | `Post ]

       The kind of a service is `Post when there is at least one POST parameters. It is `Get otherwise.

       === Attached or Non-attached ===

       type (+'a, +'b) a_s

       The abstract type for attached service representation.

       - 'a is a subtype of Eliom_service.attached_service_kind

       - 'b is a subtype of Eliom_service.getpost

       type +'a na_s

       The abstract type for non-attached service representation.

       - 'a is a subtype of Eliom_service.getpost

       type service_kind = [ `Attached of (attached_service_kind, getpost) a_s | `Nonattached of getpost na_s ]

       The type service_kind describe all four kind of services:

       -external (attached) services

       -(internal) attached services

       -(internal) attached coservices

       -(internal) non-attached coservices

       === Common subtypes of service_kind ===

       type get_service_kind = [ `Attached of (attached_service_kind, [ `Get ]) a_s | `Nonattached of [  `Get  ]
       na_s ]

       Restriction of service_kind to services without POST parameters.

       type  post_service_kind = [ `Attached of (attached_service_kind, [ `Post ]) a_s | `Nonattached of [ `Post
       ] na_s ]

       Restriction of service_kind to services with at least one POST parameters.

       type attached = [ `Attached of (attached_service_kind, getpost) a_s ]

       Restriction of service_kind to attached services.

       type nonattached = [ `Nonattached of getpost na_s ]

       Restriction of service_kind to non-attached services.

       type internal_service_kind = [ `Attached of ([ `Internal of servcoserv ], getpost) a_s | `Nonattached  of
       getpost na_s ]

       Restriction of service_kind to internal services.

       === Kind of parameters ===

       type suff = [ `WithSuffix | `WithoutSuffix ]

       The  kind  of  parameters  for  a  service  is  `WithSuffix when it have a suffix parameter, for examples
       Eliom_parameter.suffix or Eliom_parameter.suffix_prod . Otherwise it is `WithoutSuffix .

       === Registrable service ===

       type registrable = [ `Registrable | `Unregistrable ]

       A service is `Registrable only if it isn't a pre-applied service, see Eliom_service.preapply .

       === Abstract type of services ===

       type ('a, 'b, +'c, +[< suff ], +'e, +'f , +[< registrable ], +'h) service

       Type of services.

       - 'a is the type of GET parameters expected by the service.

       - 'b is the type of POST parameters expected by the service.

       - 'c describes the services's kind: attached or non-attached, internal or external, GET only or with POST
       parameters. It is a subtype of Eliom_service.service_kind .

       -the type paremeter of subtype Eliom_service.suff states the kind of parameters it uses: suffix or not.

       - 'd is the type of GET parameters names. See Eliom_parameter.param_name and  form  generation  functions
       (e. g.  Eliom_registration.Html5.get_form ).

       -  'e  is the type of POST parameters names. See Eliom_parameter.param_name and form generation functions
       (e. g.  Eliom_registration.Html5.post_form ).

       -the type parameter of subtype Eliom_service.registrable tells if it is possible to register a handler on
       this service.

       - 'f is an information on what the service returns.  See Eliom_registration.kind .

       === Registration of named modules This functionality allows one to register initialization functions  for
       Eliom modules which will be executed when the corresponding module is loaded in ocsigenserver.conf. ===

       val register_eliom_module : string -> (unit -> unit) -> unit

       The function register_eliom_module mod f is used to register the initialization function f to be executed
       when  then  module mod is "loaded" by Ocsigen server. The module mod could either be a dynamically loaded
       module or linked statically into the server: in each case, the f function will be invoked when the module
       is  initialized  in  the   configuration   file   using   <eliom   name="name">   ...   </eliom>   .   If
       register_eliom_module  is called twice with the same module name, the second initialization function will
       replace the previous one.

       === Definitions of services Warning: These  functions  must  be  called  when  the  site  information  is
       available, that is, either during a request or during the initialisation phase of the site. Otherwise, it
       will  raise  the  exception  Eliom_common.Eliom_site_information_not_available.  If  you are using static
       linking, you must delay  the  call  to  this  function  until  the  configuration  file  is  read,  using
       Eliom_service.register_eliom_module. Otherwise you will also get this exception. ===

       === Main services ===

       val service : ?https:bool -> path:Eliom_lib.Url.path -> ?keep_nl_params:[ `All | `None | `Persistent ] ->
       ?priority:int  ->  get_params:('get,  [< suff ] as 'a, 'gn) Eliom_parameter.params_type -> unit -> ('get,
       unit, [> `Attached of ([> `Internal of [> `Service ] ], [> `Get ]) a_s ], 'a, 'gn, unit, [< registrable >
       `Registrable ], 'return) service

       The function service ~path ~get_params () creates a Eliom_service.service associated to the path path and
       taking get_params as GET parameters.

       If the optional parameter ~https:true is given, all  links  towards  that  service  will  use  https.  By
       default, links will keep the current protocol.

       The  optional parameter ~priority allows one to change the priority order between service that shares the
       same path. The default priority is 0 ; if you want the service to be tried  before  (resp.  after)  other
       services, put a higher (resp. lower) priority.

       If  the optional parameter ~keep_nl_params:`Persistent (resp.  ~keep_nl_params:`All ) is given, all links
       towards that service will keep persistent (resp.  all)  non  localized  GET  parameters  of  the  current
       service. The default is `None . See the eliom manual for more information about .

       val  external_service  :  prefix:string  ->  path:Eliom_lib.Url.path  -> ?keep_nl_params:[ `All | `None |
       `Persistent ] -> get_params:('get, [< suff ] as 'a, 'gn) Eliom_parameter.params_type ->  unit  ->  ('get,
       unit,  [>  `Attached of ([> `External ], [> `Get ]) a_s ], 'a, 'gn, unit, [< registrable > `Unregistrable
       ], 'return) service

       The function external_service ~prefix ~path ~get_params () creates a service for an  external  web  site,
       that will use GET method and requires get_params as parameters. This allows one to creates links or forms
       towards other Web sites using Eliom's syntax.

       The parameter labelled ~path is the URL path. Each element of the list will be URL-encoded.

       The  parameter labelled ~prefix contains all what you want to put before the path. It usually starts with
       "http://" plus the name of the server. The prefix is not URL encoded.

       The whole URL is constructed from the prefix, the path and GET parameters. Hence, an empty prefix can  be
       used to make a link to another site of the same server.

       See Eliom_service.service for a description of the optional ~keep_nl_params parameter.

       val  external_post_service : prefix:string -> path:Eliom_lib.Url.path -> ?keep_nl_params:[ `All | `None |
       `Persistent  ]  ->  get_params:('get,  [<   suff   ]   as   'a,   'gn)   Eliom_parameter.params_type   ->
       post_params:('post,  [  `WithoutSuffix  ],  'pn)  Eliom_parameter.params_type -> unit -> ('get, 'post, [>
       `Attached of ([> `External ], [> `Post ]) a_s ],  'a,  'gn,  'pn,  [<  registrable  >  `Unregistrable  ],
       'return) service

       Same as Eliom_service.external_service but with POST method.

       val  post_service  :  ?https:bool  -> fallback:('get, unit, [ `Attached of ([ `Internal of [ `Coservice |
       `Service ] ], [ `Get ]) a_s ], [< suff ] as 'a, 'gn,  unit,  [<  `Registrable  ],  'return1)  service  ->
       ?keep_nl_params:[  `All  | `None | `Persistent ] -> ?priority:int -> post_params:('post, [ `WithoutSuffix
       ], 'pn) Eliom_parameter.params_type -> unit  ->  ('get,  'post,  [>  `Attached  of  ([>  `Internal  of  [
       `Coservice  |  `Service  ] ], [> `Post ]) a_s ], 'a, 'gn, 'pn, [< registrable > `Registrable ], 'return2)
       service

       The function post_service ~fallback ~post_params () creates a service  that  takes  post_params  as  POST
       parameters and share the same path and GET parameters than the service fallback .

       POST parameters couldn't contain a suffix parameter.

       The  service fallback should be an (internal) attached service without POST parameters ; it couldn't be a
       preapplied service.  This argument enforces the creation of an equivalent service ( i.e. a  service  with
       the  same  path and GET parameters ) to be served when POST parameters are missing. Thus, the user cannot
       put a bookmark on a page that does not exist.

       See Eliom_service.service for a description of optional ~https , ~keep_nl_params and ~priority parameters
       .

       === Attached coservices ===

       val  coservice  :  ?name:string  ->  ?csrf_safe:bool  ->  ?csrf_scope:[<  Eliom_common.user_scope  ]   ->
       ?csrf_secure:bool  ->  ?max_use:int -> ?timeout:float -> ?https:bool -> fallback:(unit, unit, [ `Attached
       of ([ `Internal of [ `Service ] ], [ `Get ]) a_s ], [ `WithoutSuffix ], unit,  unit,  [<  registrable  ],
       'return1) service -> ?keep_nl_params:[ `All | `None | `Persistent ] -> get_params:('get, [ `WithoutSuffix
       ],  'gn)  Eliom_parameter.params_type  ->  unit  ->  ('get,  unit,  [>  `Attached  of ([> `Internal of [>
       `Coservice ] ], [> `Get ]) a_s ], [ `WithoutSuffix  ],  'gn,  unit,  [<  registrable  >  `Registrable  ],
       'return2) service

       The  function  coservice ~fallback ~get_params creates an  at the same path than the service fallback and
       taking get_params as GET parameters.

       GET parameters of coservice couldn't contain a suffix parameter.

       The service fallback should be an (internal) attached service without any GET or  POST  parameters  ;  it
       could be a preapplied service.

       The  optional  ~name  parameter  Coservices  can  be  named if the ?name optional parameter is present or
       anonymous (in that case, a coservice number will be generated).

       The optional ~timeout parameter  specifies  a  timeout  (in  seconds)  after  which  the  coservice  will
       disappear.  This  amount  of time is computed from the creation or from the last call to the service. The
       default is "no timeout". The optional ~max_use parameter specifies that the service can be  used  only  a
       fixed number of times. The default is "no limitation".

       If  the  optional  ~csrf_safe  parameter is true , it will create a . In that case the ~name parameter is
       ignored. The default is false .

       The ~csrf_scope and ~csrf_secure , if present, should respectively correspond to the ~scope  and  ~secure
       parameters  that  will be given to the associated register function. Otherwise the registration will fail
       with  .  See   Eliom_registration.Html5.register   ,   Eliom_registration.App.register   or   any   other
       Eliom_registration .*.register functions for a description of those parameters.

       See Eliom_service.service for a description of the optional ~https and ~keep_nl_params parameters .

       val  post_coservice  :  ?name:string  ->  ?csrf_safe:bool  -> ?csrf_scope:[< Eliom_common.user_scope ] ->
       ?csrf_secure:bool -> ?max_use:int -> ?timeout:float -> ?https:bool -> fallback:('get, unit,  [  `Attached
       of  ([  `Internal  of  [<  `Coservice  |  `Service  ]  ], [ `Get ]) a_s ], [< suff ] as 'a, 'gn, unit, [<
       `Registrable  ],  'return1)  service  ->  ?keep_nl_params:[   `All   |   `None   |   `Persistent   ]   ->
       post_params:('post,  [  `WithoutSuffix  ],  'pn)  Eliom_parameter.params_type -> unit -> ('get, 'post, [>
       `Attached of ([> `Internal of [> `Coservice ] ], [> `Post ]) a_s  ],  'a,  'gn,  'pn,  [<  registrable  >
       `Registrable ], 'return2) service

       The  function post_coservice ~fallback ~get_params creates an  with the same path and GET parameters than
       the service fallback and taking post_params as POST parameters.

       POST parameters couldn't contain a suffix parameter.

       The service fallback should be an (internal) attached service or coservice without any POST parameters  ;
       it could be a preapplied service.

       See Eliom_service.coservice for a description of optional parameters.

       === Non attached coservices ===

       val  coservice'  :  ?name:string  ->  ?csrf_safe:bool  ->  ?csrf_scope:[<  Eliom_common.user_scope  ]  ->
       ?csrf_secure:bool -> ?max_use:int -> ?timeout:float -> ?https:bool -> ?keep_nl_params:[ `All  |  `None  |
       `Persistent ] -> get_params:('get, [ `WithoutSuffix ], 'gn) Eliom_parameter.params_type -> unit -> ('get,
       unit,  [>  `Nonattached of [> `Get ] na_s ], [ `WithoutSuffix ], 'gn, unit, [< registrable > `Registrable
       ], 'return) service

       The function coservice' ~get_param creates a  taking get_params as extra GET parameters.

       GET parameters of coservice' couldn't contain a suffix parameter.

       See Eliom_service.service for a description of the optional ~https and ~keep_nl_params parameters  ;  see
       Eliom_service.coservice for others optional parameters.

       val  post_coservice'  :  ?name:string  ->  ?csrf_safe:bool -> ?csrf_scope:[< Eliom_common.user_scope ] ->
       ?csrf_secure:bool -> ?max_use:int -> ?timeout:float -> ?https:bool -> ?keep_nl_params:[ `All  |  `None  |
       `Persistent   ]   ->   ?keep_get_na_params:bool   ->   post_params:('post,   [   `WithoutSuffix  ],  'pn)
       Eliom_parameter.params_type ->  unit  ->  (unit,  'post,  [>  `Nonattached  of  [>  `Post  ]  na_s  ],  [
       `WithoutSuffix ], unit, 'pn, [< registrable > `Registrable ], 'return) service

       The function post_coservice' ~get_param creates a  taking post_params as POST parameters.

       POST parameters couldn't contain a suffix parameter.

       If  the optional parameter ~keep_get_na_params is false , GET non-attached parameters of the current page
       won't be kept in the URL (if any) when you create a POST form to this coservice. The default is true.

       See Eliom_service.service for a description of the optional ~https and ~keep_nl_params parameters  ;  see
       Eliom_service.coservice for others optional parameters.

       === Predefined services ===

       === Static files ===

       val static_dir : unit -> (string list, unit, [> `Attached of ([> `Internal of [> `Service ] ], [> `Get ])
       a_s  ],  [  `WithSuffix  ],  [  `One  of string list ] Eliom_parameter.param_name, unit, [< registrable >
       `Unregistrable ], 'return) service

       The predefined service static_dir allows one to create links to static files. This service takes the name
       of a static file as a parameter (a string list, slash separated).  The  actual  directory  in  filesystem
       where static pages will be found must be set up in the configuration file with the staticmod extension.

       val  https_static_dir  : unit -> (string list, unit, [> `Attached of ([> `Internal of [> `Service ] ], [>
       `Get ]) a_s ], [ `WithSuffix ], [ `One of string list ] Eliom_parameter.param_name, unit, [<  registrable
       > `Unregistrable ], 'return) service

       Same as Eliom_service.static_dir but forcing https link.

       val  static_dir_with_params  :  ?keep_nl_params:[  `All  |  `None  |  `Persistent  ] -> get_params:('a, [
       `WithoutSuffix ], 'an) Eliom_parameter.params_type -> unit -> (string list * 'a, unit,  [>  `Attached  of
       ([>  `Internal  of  [>  `Service  ]  ],  [>  `Get  ])  a_s  ],  [  `WithSuffix ], [ `One of string list ]
       Eliom_parameter.param_name * 'an, unit, [< registrable > `Unregistrable ], 'return) service

       Like static_dir , but allows one to put GET parameters

       val https_static_dir_with_params : ?keep_nl_params:[ `All | `None | `Persistent ]  ->  get_params:('a,  [
       `WithoutSuffix  ],  'an)  Eliom_parameter.params_type -> unit -> (string list * 'a, unit, [> `Attached of
       ([> `Internal of [> `Service ] ], [>  `Get  ])  a_s  ],  [  `WithSuffix  ],  [  `One  of  string  list  ]
       Eliom_parameter.param_name * 'an, unit, [< registrable > `Unregistrable ], 'return) service

       Same as Eliom_service.static_dir_with_params but forcing https link.

       === Void non-attached coservices ===

       val  void_coservice'  :  (unit,  unit,  [>  `Nonattached of 'a na_s ], [ `WithoutSuffix ], unit, unit, [<
       registrable > `Unregistrable ], 'return) service

       The service void_coservice' is a predefined  non-attached  action  with  special  behaviour:  it  has  no
       parameter  at  all,  even non-attached parameters.  Use it if you want to make a link to the current page
       without non-attached parameters.  It is almost equivalent to a POST  non-attached  service  without  POST
       parameters,  on  which  you  register an action that does nothing, but you can use it with <a> links, not
       only forms.  It does not keep non attached GET parameters.

       val https_void_coservice' : (unit, unit, [> `Nonattached of 'a na_s ], [ `WithoutSuffix ], unit, unit, [<
       registrable > `Unregistrable ], 'return) service

       Same as Eliom_service.void_coservice' but forcing https.

       val void_hidden_coservice' : (unit, unit, [> `Nonattached of 'a na_s ], [ `WithoutSuffix ],  unit,  unit,
       [< registrable > `Unregistrable ], 'return) service

       Same as Eliom_service.void_coservice' but keeps non attached GET parameters.

       val  https_void_hidden_coservice'  : (unit, unit, [> `Nonattached of 'a na_s ], [ `WithoutSuffix ], unit,
       unit, [< registrable > `Unregistrable ], 'return) service

       Same as Eliom_service.void_hidden_coservice' but forcing https.

       === Miscellaneous ===

       val preapply : service:('a, 'b, [> `Attached of ('d, 'dd) a_s ] as 'c, [< suff ], 'e, 'f, [<  registrable
       ], 'return) service -> 'a -> (unit, 'b, 'c, [ `WithoutSuffix ], unit, 'f, [< registrable > `Unregistrable
       ], 'return) service

       The  function  preapply  ~service  paramaters  creates  a  new  service by preapplying service to the GET
       parameters . It is not possible to register a handler on an preapplied service ; preapplied services  may
       be used in links or as fallbacks for coservices

       val      add_non_localized_get_parameters      :     params:('p,     [     `WithoutSuffix     ],     'pn)
       Eliom_parameter.non_localized_params -> service:('a, 'b, 'c, [< suff ] as 'd, 'e, 'f, [< registrable ] as
       'g, 'return) service -> ('a * 'p, 'b, 'c, 'd, 'e * 'pn, 'f, 'g, 'return) service

       The function add_non_localized_get_parameters ~params ~service Adds non localized GET  parameters  params
       to service . See the Eliom manual for more information about .

       val      add_non_localized_post_parameters     :     params:('p,     [     `WithoutSuffix     ],     'pn)
       Eliom_parameter.non_localized_params -> service:('a, 'b, 'c, [< suff ] as 'd, 'e, 'f, [< registrable ] as
       'g, 'return) service -> ('a, 'b * 'p, 'c, 'd, 'e, 'f * 'pn, 'g, 'return) service

       Same as Eliom_service.add_non_localized_get_parameters but with POST parameters.

       val unregister : ?scope:[< Eliom_common.scope ] -> ?secure:bool -> ('a, 'b, [< `Attached of ([> `Internal
       of 'c ], [< `Get | `Post ]) a_s | `Nonattached of 'd na_s ],  [<  suff  ],  'f,  'g,  [<  registrable  ],
       'return) service -> unit

       The  function  unregister  service  unregister  the service handler previously associated to service with
       Eliom_registration.Html5.register  ,  Eliom_registration.App.register  or  any  other  Eliom_registration
       .*.register  functions.  See  the  documentation  of  those functions for a description of the ~scope and
       ~secure optional parameters.

OCamldoc                                           2014-02-04                                  Eliom_service(3o)