--- name: "Eliom_service.server" section: "3o" platform: "linux" package: "libeliom-ocaml-doc" version: "4.0.0-2" release: "Debian 8 (Jessie)" platforms: ["linux"] url: "https://new.carta.tech/Eliom_service.server" --- # Eliom\_service.server(3o) Creation and manipulation of Eliom services. ## 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** **{% \<\\> %}.** **{% \<\\> \>\> %} ===** **=== The main functions to create services are in modules** **{% \<\\> %} (default),** **{% \<\\> %}** **(for services returning OCaml values) and** **{% \<\\> %}** **(for services belonging to an Eliom client-server app). ===** **===** **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* = **\[ \`Delete \| \`Get \| \`Post \| \`Put \]** 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 GET services. *type post\_service\_kind* = **\[ \`Attached of** **(attached\_service\_kind, \[ \`Post \]) a\_s** **\| \`Nonattached of \[ \`Post \] na\_s \]** Restriction of **service\_kind** to POST services. *type put\_service\_kind* = **\[ \`Attached of** **(attached\_service\_kind, \[ \`Put \]) a\_s** **\| \`Nonattached of \[ \`Put \] na\_s \]** Restriction of **service\_kind** to PUT services. *type delete\_service\_kind* = **\[ \`Attached of** **(attached\_service\_kind, \[ \`Delete \]) a\_s** **\| \`Nonattached of \[ \`Delete \] na\_s \]** Restriction of **service\_kind** to DELETE services. *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\_content.Html5.D.get\_form** ). \- **'e** is the type of POST parameters names. See **Eliom\_parameter.param\_name** and form generation functions (e. g. **Eliom\_content.Html5.D.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** . *type http\_service* = **\[ \`Http \]** Types of groups of services. *type appl\_service* = **\[ \`Appl \]** *type* **'a** *ocaml\_service* *type non\_ocaml\_service* = **\[ \`Appl \| \`Http \]** The type **non\_ocaml\_service** is used as phantom type parameters for the **Eliom\_registration.kind** . It used to type functions that operates over service that do not returns OCaml values, like **appl\_self\_redirect** . *type* **'rt** *rt* Helper for typing OCaml services. In some cases, you may need to write the return type of the service manually. Instead of writing the full type of the service, (which may be huge), add a type constraint for parameter **?rt** of service creation functions (like \<\\>), using the following value. *val rt* : **'rt rt** **===** **Registration of services** **===** *module Http :* **sig end** Default module for creating services *module App :* **sig end** Module for creating services returning applications *module Ocaml :* **sig end** Module for creating services that return OCaml values *module Unsafe :* **sig end** Module for creating services without specifying the return type **===** **Static loading of Eliom 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.** **If the module is loaded dynamically, you probably don't need this.** **But if the module is linked statically, some computations,** **like service registrations must be delayed. ===** *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 **\** **... \** . If **register\_eliom\_module** is called twice with the same module name, the second initialization function will replace the previous one. **===** **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 \],** **\[\> http\_service \])** **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 \],** **\[\> http\_service \])** **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 \],** **\[\> http\_service \])** **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 \],** **\[\> http\_service \])** **service** Same as **Eliom\_service.static\_dir\_with\_params** but forcing https link. **===** **Void non-attached coservices** **===** *val void\_coservice'* : **(unit, unit, \[\> \`Nonattached of \[\> \`Get \] na\_s \],** **\[ \`WithoutSuffix \], unit, unit,** **\[\< registrable \> \`Unregistrable \],** **\[\> non\_ocaml\_service \])** **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 \ links, not only forms. It does not keep non attached GET parameters. *val https\_void\_coservice'* : **(unit, unit, \[\> \`Nonattached of \[\> \`Get \] na\_s \],** **\[ \`WithoutSuffix \], unit, unit,** **\[\< registrable \> \`Unregistrable \],** **\[\> non\_ocaml\_service \])** **service** Same as **Eliom\_service.void\_coservice'** but forcing https. *val void\_hidden\_coservice'* : **(unit, unit, \[\> \`Nonattached of \[\> \`Get \] na\_s \],** **\[ \`WithoutSuffix \], unit, unit,** **\[\< registrable \> \`Unregistrable \],** **\[\> non\_ocaml\_service \])** **service** Same as **Eliom\_service.void\_coservice'** but keeps non attached GET parameters. *val https\_void\_hidden\_coservice'* : **(unit, unit, \[\> \`Nonattached of \[\> \`Get \] na\_s \],** **\[ \`WithoutSuffix \], unit, unit,** **\[\< registrable \> \`Unregistrable \],** **\[\> non\_ocaml\_service \])** **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 attach\_coservice'* : **fallback:(unit, unit,** **\[\< \`Attached of** **(\[\< \`Internal of 'sc1 \], \[\< \`Get \]) a\_s \],** **\[\< suff \], unit, unit,** **\[\< registrable \], 'return1)** **service -\>** **service:('get, 'post, \[\< \`Nonattached of 'gp na\_s \],** **\[\< \`WithoutSuffix \] as 'a, 'gn, 'pn, \[\< registrable \],** **'return)** **service -\>** **('get, 'post,** **\[\> \`Attached of (\[\> \`Internal of \[\> \`Coservice \] \], 'gp) a\_s \],** **'a, 'gn, 'pn, \[\< registrable \> \`Unregistrable \], 'return)** **service** **attach\_coservice' ~fallback ~service** attaches the non-attached coservice **service** on the URL of **fallback** . This allows to create a link to a non-attached coservice but with another URL than the current one. It is not possible to register something on the service returned by this function. *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 \], \[\< \`Delete \| \`Get \| \`Post \| \`Put \])** **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.