# Module Eliom_services

    module Eliom_services: sig .. end

This module allows to define services.

    val sync : ('a -> 'b -> 'c -> 'd) -> 'a -> 'b -> 'c -> 'd Lwt.t

This function may be used for services that cannot be interrupted (no cooperation point for threads). It is defined by `let sync f sp g p = Lwt.return (f sp g p)`
`type ``cookie =`

`|` | `Set of `Ocsigen_extensions.url_path option * float option * string * string * bool``
`|` | `Unset of `Ocsigen_extensions.url_path option * string``

Type used for other cookies to set or unset. The float option is the timestamp for the expiration date. The strings are names and values.

    val cookie_table_of_eliom_cookies : ?oldtable:Ocsigen_http_frame.cookieset ->
           sp:Eliom_sessions.server_params ->
           cookie list -> Ocsigen_http_frame.cookieset

Conversion fonction from Eliom cookies to server cookies. If `?oldtable` is present, cookies are added to this table
`type ``result_to_send =`

`|` | `EliomResult of `Ocsigen_http_frame.result``
`|` | `EliomExn of `(exn list * cookie list)``

The type to send if you want to create your own modules for generating pages

## Types of services

    type suff = [ `WithSuffix | `WithoutSuffix ]

    type servcoserv = [ `Coservice | `Service ]

    type getpost = [ `Get | `Post ]

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

    type get_attached_service_kind = [ `External | `Internal of servcoserv * [ `Get ] ]

    type post_attached_service_kind = [ `External | `Internal of servcoserv * [ `Post ] ]

    type internal = [ `Internal of servcoserv * getpost ]

    type registrable = [ `Registrable | `Unregistrable ]

You can call register function only on registrable services

    type +'a a_s

    type +'a na_s

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

    type get_service_kind = [ `Attached of get_attached_service_kind a_s
           | `Nonattached of [ `Get ] na_s ]

    type post_service_kind = [ `Attached of post_attached_service_kind a_s
           | `Nonattached of [ `Post ] na_s ]

    type internal_service_kind = [ `Attached of internal a_s
           | `Nonattached of getpost na_s ]

    type attached = [ `Attached of attached_service_kind a_s ]

    type nonattached = [ `Nonattached of getpost na_s ]

    type ('a, 'b, +'c, +'d, +'e, +'f, +'g) service

Type of services.

- `'get` is the type of GET parameters
- `'post` is the type of POST parameters
- `'kind` is a subtype of `Eliom_services.service_kind` (attached or non-attached service, internal or external, GET only or with POST parameters)
- `'tipo` is a phantom type stating the kind of parameters it uses (suffix or not)
- `'getnames` is the type of GET parameters names
- `'postnames` is the type of POST parameters names
- `'registrable` is a phantom type, subtype of `Eliom_services.registrable`, telling if it is possible to register a handler on this service.

## Definitions of services

### Main services

    val new_service : ?sp:Eliom_sessions.server_params ->
           ?https:bool ->
           path:Ocsigen_extensions.url_path ->
           get_params:('a, [< suff ] as 'b, 'c)
                      Eliom_parameters.params_type ->
           unit ->
           ('a, unit,
            [> `Attached of
                 [> `Internal of [> `Service ] * [> `Get ] ] a_s ],
            'b, 'c, unit, [> `Registrable ])
           service

`new_service ~path:p ~get_params:pa ()` creates an `Eliom_services.service` associated to the path `p`, taking the GET parameters `pa`.

If `~https` is true, all links towards that service will use https.

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 new_service' : ?sp:Eliom_sessions.server_params ->
           ?https:bool ->
           name:string ->
           get_params:('a, [ `WithoutSuffix ], 'b) Eliom_parameters.params_type ->
           unit ->
           ('a, unit, [> `Nonattached of [> `Get ] na_s ],
            [ `WithoutSuffix ], 'b, unit, [> `Registrable ])
           service

`new_service' ~name:n ~get_params:pa ()` creates a non-attached service associated to the name `n`, taking the GET parameters `pa`.

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 new_external_service : prefix:string ->
           path:Ocsigen_extensions.url_path ->
           get_params:('a, [< suff ] as 'b, 'c)
                      Eliom_parameters.params_type ->
           post_params:('d, [ `WithoutSuffix ], 'e) Eliom_parameters.params_type ->
           unit ->
           ('a, 'd, [> `Attached of [> `External ] a_s ], 'b, 'c, 'e,
            [> `Unregistrable ])
           service

Creates an service for an external web site. Allows to creates links or forms towards other Web sites using Eliom's syntax.

The parameter labelled `~path` is the URL path, and 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 whole URL is constructed from the prefix, the path and parameters. The prefix is not encoded. An empty prefix can be used to make a link to another site of the same server.

    val new_post_service : ?sp:Eliom_sessions.server_params ->
           ?https:bool ->
           fallback:('a, unit,
                     [ `Attached of
                         [ `Internal of [ `Coservice | `Service ] * [ `Get ] ]
                         a_s ],
                     [< suff ] as 'b, 'c, unit, [< `Registrable ])
                    service ->
           post_params:('d, [ `WithoutSuffix ], 'e) Eliom_parameters.params_type ->
           unit ->
           ('a, 'd,
            [> `Attached of
                 [> `Internal of [ `Coservice | `Service ] * [> `Post ] ]
                 a_s ],
            'b, 'c, 'e, [> `Registrable ])
           service

Creates an service that takes POST parameters. `fallback` is the a service without POST parameters. You can't create an service with POST parameters if the same service does not exist without POST parameters. Thus, the user can't bookmark a page that does not exist.

    val new_post_service' : ?keep_get_na_params:bool ->
           ?https:bool ->
           name:string ->
           post_params:('a, [ `WithoutSuffix ], 'b) Eliom_parameters.params_type ->
           unit ->
           (unit, 'a, [> `Nonattached of [> `Post ] na_s ],
            [ `WithoutSuffix ], unit, 'b, [> `Registrable ])
           service

Creates a non-attached service that takes POST parameters. `name` is the name of that non-attached service.

### Attached coservices

    val new_coservice : ?max_use:int ->
           ?timeout:float ->
           ?https:bool ->
           fallback:(unit, unit,
                     [ `Attached of
                         [ `Internal of [ `Service ] * [ `Get ] ] a_s ],
                     [ `WithoutSuffix ], unit, unit, [< registrable ])
                    service ->
           get_params:('a, [ `WithoutSuffix ], 'b) Eliom_parameters.params_type ->
           unit ->
           ('a, unit,
            [> `Attached of
                 [> `Internal of [> `Coservice ] * [> `Get ] ] a_s ],
            [ `WithoutSuffix ], 'b, unit, [> `Registrable ])
           service

Creates a coservice. A coservice is another version of an already existing main service, where you can register another handler. The two versions are automatically distinguished using an extra parameter added automatically by Eliom. It allows to have several links towards the same page, that will behave differently, or to create services dedicated to one user. See the tutorial for more informations.

    val new_post_coservice : ?max_use:int ->
           ?timeout:float ->
           ?https:bool ->
           fallback:('a, unit,
                     [ `Attached of
                         [ `Internal of [< `Coservice | `Service ] * [ `Get ] ]
                         a_s ],
                     [< suff ] as 'b, 'c, unit, [< `Registrable ])
                    service ->
           post_params:('d, [ `WithoutSuffix ], 'e) Eliom_parameters.params_type ->
           unit ->
           ('a, 'd,
            [> `Attached of
                 [> `Internal of [> `Coservice ] * [> `Post ] ] a_s ],
            'b, 'c, 'e, [> `Registrable ])
           service

Creates a coservice with POST parameters

### Non attached coservices

    val new_coservice' : ?max_use:int ->
           ?timeout:float ->
           ?https:bool ->
           get_params:('a, [ `WithoutSuffix ], 'b) Eliom_parameters.params_type ->
           unit ->
           ('a, unit, [> `Nonattached of [> `Get ] na_s ],
            [ `WithoutSuffix ], 'b, unit, [> `Registrable ])
           service

Creates a non-attached coservice, that is, services that do not correspond to a precise URL. Links towards such services will not change the URL, just add extra parameters. See the tutorial for more informations.

    val new_post_coservice' : ?max_use:int ->
           ?timeout:float ->
           ?keep_get_na_params:bool ->
           ?https:bool ->
           post_params:('a, [ `WithoutSuffix ], 'b) Eliom_parameters.params_type ->
           unit ->
           (unit, 'a, [> `Nonattached of [> `Post ] na_s ],
            [ `WithoutSuffix ], unit, 'b, [> `Registrable ])
           service

Creates a non attached coservice with POST parameters. If the optional parameter `~keep_get_na_params` is `false`, GET non-attached parameters won't be kept in the URL (if any) when you create a POST form to this coservice. Default is `true`. See also `Eliom_mkforms.ELIOMFORMSIG.post_form`.

## Misc

    val static_dir : sp:Eliom_sessions.server_params ->
           (string list, unit,
            [> `Attached of
                 [> `Internal of [> `Service ] * [> `Get ] ] a_s ],
            [ `WithSuffix ], [ `One of string list ] Eliom_parameters.param_name,
            unit, [> `Unregistrable ])
           service

A predefined service that correponds to the directory where static pages are. This directory is chosen in the config file (ocsigen.conf). This service takes the name of the static file as a parameter (a string list, slash separated).

    val https_static_dir : sp:Eliom_sessions.server_params ->
           (string list, unit,
            [> `Attached of
                 [> `Internal of [> `Service ] * [> `Get ] ] a_s ],
            [ `WithSuffix ], [ `One of string list ] Eliom_parameters.param_name,
            unit, [> `Unregistrable ])
           service

The same, but forcing https

    val static_dir_with_params : sp:Eliom_sessions.server_params ->
           get_params:('a, [ `WithoutSuffix ], 'b) Eliom_parameters.params_type ->
           (string list * 'a, unit,
            [> `Attached of
                 [> `Internal of [> `Service ] * [> `Get ] ] a_s ],
            [ `WithSuffix ], [ `One of string list ] Eliom_parameters.param_name * 'b,
            unit, [> `Unregistrable ])
           service

Like `static_dir`, but allows to put GET parameters

    val https_static_dir_with_params : sp:Eliom_sessions.server_params ->
           get_params:('a, [ `WithoutSuffix ], 'b) Eliom_parameters.params_type ->
           (string list * 'a, unit,
            [> `Attached of
                 [> `Internal of [> `Service ] * [> `Get ] ] a_s ],
            [ `WithSuffix ], [ `One of string list ] Eliom_parameters.param_name * 'b,
            unit, [> `Unregistrable ])
           service

The same, but forcing https

    val void_action : (unit, unit, [> `Nonattached of 'a na_s ], [ `WithoutSuffix ],
            unit, unit, [> `Unregistrable ])
           service

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.

    val https_void_action : (unit, unit, [> `Nonattached of 'a na_s ], [ `WithoutSuffix ],
            unit, unit, [> `Unregistrable ])
           service

The same, but forcing https.

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

creates a new service by preapplying a service to 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

## Using your own error pages

    val set_exn_handler : ?sp:Eliom_sessions.server_params ->
           (Eliom_sessions.server_params -> exn -> result_to_send Lwt.t) ->
           unit

allows to use your own error pages (404, or any exception during page generation).

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