.TH "Eliom_service.Ocaml" 3o 2014-07-10 OCamldoc "" .SH NAME Eliom_service.Ocaml \- Module for creating services that return OCaml values .SH Module Module Eliom_service.Ocaml .SH Documentation .sp Module .BI "Ocaml" : .B sig end .sp Module for creating services that return OCaml values .sp .sp .sp .sp .PP .B === .B Definitions of services .B .B .B Warning: These functions must be called when the site .B information is available, that is, either during a request or .B during the initialisation phase of the site\&. Otherwise, it will .B raise the exception .B Eliom_common\&.Eliom_site_information_not_available\&. If you are .B using static linking, you must delay the call to this function .B until the configuration file is read, using .B Eliom_service\&.register_eliom_module\&. Otherwise you will also .B get this exception\&. === .PP .PP .B === .B Main services .B === .PP .I val service : .B ?rt:'rt Eliom_service.rt -> .B ?https:bool -> .B path:Eliom_lib.Url.path -> .B ?keep_nl_params:[ `All | `None | `Persistent ] -> .B ?priority:int -> .B get_params:('get, [< Eliom_service.suff ] as 'a, 'gn) .B Eliom_parameter.params_type -> .B unit -> .B ('get, unit, .B [> `Attached of .B ([> `Internal of [> `Service ] ], [> `Get ]) Eliom_service.a_s ], .B 'a, 'gn, unit, [< Eliom_service.registrable > `Registrable ], .B 'rt Eliom_service.ocaml_service) .B Eliom_service.service .sp The function .B service ~path ~get_params () creates a .B Eliom_service\&.Ocaml\&.service associated to the path .B path and taking .B get_params as GET parameters\&. .sp If the optional parameter .B ~https:true is given, all links towards that service will use https\&. By default, links will keep the current protocol\&. .sp The optional parameter .B ~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\&. .sp If the optional parameter .B ~keep_nl_params:`Persistent (resp\&. .B ~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 .B `None \&. See the eliom manual for more information about \&. .sp The optional parameter .B ?rt is used to constrain the type parameter .B \&'rt of the service in the case it is .B \&'rt Eliom_service\&.ocaml_service \&. Example: .B service ~rt:(Eliom_service\&.rt : your_return_type Eliom_service\&.rt) \&. .sp .sp .I val post_service : .B ?rt:'rt Eliom_service.rt -> .B ?https:bool -> .B fallback:('get, unit, .B [ `Attached of .B ([ `Internal of [ `Coservice | `Service ] ], [ `Get ]) .B Eliom_service.a_s ], .B [< Eliom_service.suff ] as 'a, 'gn, unit, [< `Registrable ], .B 'rt Eliom_service.ocaml_service) .B Eliom_service.service -> .B ?keep_nl_params:[ `All | `None | `Persistent ] -> .B ?priority:int -> .B post_params:('post, [ `WithoutSuffix ], 'pn) Eliom_parameter.params_type -> .B unit -> .B ('get, 'post, .B [> `Attached of .B ([> `Internal of [ `Coservice | `Service ] ], [> `Post ]) .B Eliom_service.a_s ], .B 'a, 'gn, 'pn, [< Eliom_service.registrable > `Registrable ], .B 'rt Eliom_service.ocaml_service) .B Eliom_service.service .sp The function .B post_service ~fallback ~post_params () creates a service that takes .B post_params as POST parameters and share the same path and GET parameters than the service .B fallback \&. .sp POST parameters couldn\&'t contain a suffix parameter\&. .sp The service .B 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\&. .sp See .B Eliom_service\&.Ocaml\&.service for a description of optional .B ~https , .B ~keep_nl_params , .B ~priority and .B ~rt parameters \&. .sp .sp .I val put_service : .B ?rt:'rt Eliom_service.rt -> .B ?https:bool -> .B path:Eliom_lib.Url.path -> .B ?keep_nl_params:[ `All | `None | `Persistent ] -> .B ?priority:int -> .B get_params:('get, [< Eliom_service.suff ] as 'a, 'gn) .B Eliom_parameter.params_type -> .B unit -> .B ('get, Eliom_parameter.raw_post_data, .B [> `Attached of .B ([> `Internal of [> `Service ] ], [> `Put ]) Eliom_service.a_s ], .B 'a, 'gn, Eliom_parameter.no_param_name, .B [< Eliom_service.registrable > `Registrable ], .B 'rt Eliom_service.ocaml_service) .B Eliom_service.service .sp The function .B put_service ~path ~get_params () creates a service that answers the HTTP PUT method, and only takes .B Eliom_parameter\&.raw_post_data as POST parameter\&. .sp .B path and .B get_params , however, can be set at will\&. .sp See .B Eliom_service\&.Ocaml\&.service for a description of optional .B ~https , .B ~keep_nl_params , .B ~priority and .B ~rt parameters \&. .sp .sp .I val delete_service : .B ?rt:'rt Eliom_service.rt -> .B ?https:bool -> .B path:Eliom_lib.Url.path -> .B ?keep_nl_params:[ `All | `None | `Persistent ] -> .B ?priority:int -> .B get_params:('get, [< Eliom_service.suff ] as 'a, 'gn) .B Eliom_parameter.params_type -> .B unit -> .B ('get, Eliom_parameter.raw_post_data, .B [> `Attached of .B ([> `Internal of [> `Service ] ], [> `Delete ]) Eliom_service.a_s ], .B 'a, 'gn, Eliom_parameter.no_param_name, .B [< Eliom_service.registrable > `Registrable ], .B 'rt Eliom_service.ocaml_service) .B Eliom_service.service .sp The function .B delete_service ~path ~get_params () creates a service that answers the HTTP DELETE method, and only takes .B Eliom_parameter\&.raw_post_data as POST parameter\&. .sp .B path and .B get_params , however, can be set at will\&. .sp See .B Eliom_service\&.Ocaml\&.service for a description of optional .B ~https , .B ~keep_nl_params , .B ~priority and .B ~rt parameters \&. .sp .sp .PP .B === .B Attached coservices .B === .PP .I val coservice : .B ?rt:'rt Eliom_service.rt -> .B ?name:string -> .B ?csrf_safe:bool -> .B ?csrf_scope:[< Eliom_common.user_scope ] -> .B ?csrf_secure:bool -> .B ?max_use:int -> .B ?timeout:float -> .B ?https:bool -> .B fallback:(unit, unit, .B [ `Attached of .B ([ `Internal of [ `Service ] ], [ `Get ]) Eliom_service.a_s ], .B [ `WithoutSuffix ], unit, unit, [< Eliom_service.registrable ], .B 'rt Eliom_service.ocaml_service) .B Eliom_service.service -> .B ?keep_nl_params:[ `All | `None | `Persistent ] -> .B get_params:('get, [ `WithoutSuffix ], 'gn) Eliom_parameter.params_type -> .B unit -> .B ('get, unit, .B [> `Attached of .B ([> `Internal of [> `Coservice ] ], [> `Get ]) Eliom_service.a_s ], .B [ `WithoutSuffix ], 'gn, unit, .B [< Eliom_service.registrable > `Registrable ], .B 'rt Eliom_service.ocaml_service) .B Eliom_service.service .sp The function .B coservice ~fallback ~get_params creates an at the same path than the service .B fallback and taking .B get_params as GET parameters\&. .sp GET parameters of .B coservice couldn\&'t contain a suffix parameter\&. .sp The service .B fallback should be an (internal) attached service without any GET or POST parameters ; it could be a preapplied service\&. .sp The optional .B ~name parameter Coservices can be named if the .B ?name optional parameter is present or anonymous (in that case, a coservice number will be generated)\&. .sp The optional .B ~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 .B ~max_use parameter specifies that the service can be used only a fixed number of times\&. The default is "no limitation"\&. .sp If the optional .B ~csrf_safe parameter is .B true , it will create a \&. In that case the .B ~name parameter is ignored\&. The default is .B false \&. .sp The .B ~csrf_scope and .B ~csrf_secure , if present, should respectively correspond to the .B ~scope and .B ~secure parameters that will be given to the associated .B register function\&. Otherwise the registration will fail with \&. See .B Eliom_registration\&.Html5\&.register , .B Eliom_registration\&.App\&.register or any other .B Eliom_registration .B \&.*\&.register functions for a description of those parameters\&. .sp See .B Eliom_service\&.Ocaml\&.service for a description of the optional .B ~https , .B ~rt and .B ~keep_nl_params parameters \&. .sp .sp .I val post_coservice : .B ?rt:'rt Eliom_service.rt -> .B ?name:string -> .B ?csrf_safe:bool -> .B ?csrf_scope:[< Eliom_common.user_scope ] -> .B ?csrf_secure:bool -> .B ?max_use:int -> .B ?timeout:float -> .B ?https:bool -> .B fallback:('get, unit, .B [ `Attached of .B ([ `Internal of [< `Coservice | `Service ] ], [ `Get ]) .B Eliom_service.a_s ], .B [< Eliom_service.suff ] as 'a, 'gn, unit, [< `Registrable ], .B 'rt Eliom_service.ocaml_service) .B Eliom_service.service -> .B ?keep_nl_params:[ `All | `None | `Persistent ] -> .B post_params:('post, [ `WithoutSuffix ], 'pn) Eliom_parameter.params_type -> .B unit -> .B ('get, 'post, .B [> `Attached of .B ([> `Internal of [> `Coservice ] ], [> `Post ]) Eliom_service.a_s ], .B 'a, 'gn, 'pn, [< Eliom_service.registrable > `Registrable ], .B 'rt Eliom_service.ocaml_service) .B Eliom_service.service .sp The function .B post_coservice ~fallback ~post_params creates an with the same path and GET parameters than the service .B fallback and taking .B post_params as POST parameters\&. .sp POST parameters couldn\&'t contain a suffix parameter\&. .sp The service .B fallback should be an (internal) attached service or coservice without any POST parameters ; it could be a preapplied service\&. .sp See .B Eliom_service\&.Ocaml\&.coservice for a description of optional parameters\&. .sp .sp .I val put_coservice : .B ?rt:'rt Eliom_service.rt -> .B ?name:string -> .B ?csrf_safe:bool -> .B ?csrf_scope:[< Eliom_common.user_scope ] -> .B ?csrf_secure:bool -> .B ?max_use:int -> .B ?timeout:float -> .B ?https:bool -> .B fallback:(unit, Eliom_parameter.raw_post_data, .B [ `Attached of .B ([ `Internal of [ `Service ] ], [ `Put ]) Eliom_service.a_s ], .B [ `WithoutSuffix ], unit, Eliom_parameter.no_param_name, .B [< Eliom_service.registrable ], 'rt Eliom_service.ocaml_service) .B Eliom_service.service -> .B ?keep_nl_params:[ `All | `None | `Persistent ] -> .B get_params:('get, [ `WithoutSuffix ], 'gn) Eliom_parameter.params_type -> .B unit -> .B ('get, Eliom_parameter.raw_post_data, .B [> `Attached of .B ([> `Internal of [> `Coservice ] ], [> `Put ]) Eliom_service.a_s ], .B [ `WithoutSuffix ], 'gn, Eliom_parameter.no_param_name, .B [< Eliom_service.registrable > `Registrable ], .B 'rt Eliom_service.ocaml_service) .B Eliom_service.service .sp The function .B put_coservice ~fallback ~get_params creates an with the same path and GET parameters than the service .B fallback and taking a single POST parameter of type .B Eliom_parameter\&.raw_post_data \&. .sp The service .B fallback should be an (internal) attached PUT service or coservice without any GET parameters ; it could be a preapplied service\&. .sp See .B Eliom_service\&.Ocaml\&.coservice for a description of optional parameters\&. .sp .sp .I val delete_coservice : .B ?rt:'rt Eliom_service.rt -> .B ?name:string -> .B ?csrf_safe:bool -> .B ?csrf_scope:[< Eliom_common.user_scope ] -> .B ?csrf_secure:bool -> .B ?max_use:int -> .B ?timeout:float -> .B ?https:bool -> .B fallback:(unit, Eliom_parameter.raw_post_data, .B [ `Attached of .B ([ `Internal of [ `Service ] ], [ `Delete ]) Eliom_service.a_s ], .B [ `WithoutSuffix ], unit, Eliom_parameter.no_param_name, .B [< Eliom_service.registrable ], 'rt Eliom_service.ocaml_service) .B Eliom_service.service -> .B ?keep_nl_params:[ `All | `None | `Persistent ] -> .B get_params:('get, [ `WithoutSuffix ], 'gn) Eliom_parameter.params_type -> .B unit -> .B ('get, Eliom_parameter.raw_post_data, .B [> `Attached of .B ([> `Internal of [> `Coservice ] ], [> `Delete ]) Eliom_service.a_s ], .B [ `WithoutSuffix ], 'gn, Eliom_parameter.no_param_name, .B [< Eliom_service.registrable > `Registrable ], .B 'rt Eliom_service.ocaml_service) .B Eliom_service.service .sp The function .B delete_coservice ~fallback ~get_params creates an with the same path and GET parameters than the service .B fallback and taking a single POST parameter of type .B Eliom_parameter\&.raw_post_data \&. .sp The service .B fallback should be an (internal) attached DELETE service or coservice without any GET parameters ; it could be a preapplied service\&. .sp See .B Eliom_service\&.Ocaml\&.coservice for a description of optional parameters\&. .sp .sp .PP .B === .B Non attached coservices .B === .PP .I val coservice' : .B ?rt:'rt Eliom_service.rt -> .B ?name:string -> .B ?csrf_safe:bool -> .B ?csrf_scope:[< Eliom_common.user_scope ] -> .B ?csrf_secure:bool -> .B ?max_use:int -> .B ?timeout:float -> .B ?https:bool -> .B ?keep_nl_params:[ `All | `None | `Persistent ] -> .B get_params:('get, [ `WithoutSuffix ], 'gn) Eliom_parameter.params_type -> .B unit -> .B ('get, unit, [> `Nonattached of [> `Get ] Eliom_service.na_s ], .B [ `WithoutSuffix ], 'gn, unit, .B [< Eliom_service.registrable > `Registrable ], .B 'rt Eliom_service.ocaml_service) .B Eliom_service.service .sp The function .B coservice\&' ~get_param creates a taking .B get_params as extra GET parameters\&. .sp GET parameters of .B coservice\&' couldn\&'t contain a suffix parameter\&. .sp See .B Eliom_service\&.Ocaml\&.service for a description of the optional .B ~https , .B ~rt and .B ~keep_nl_params parameters ; see .B Eliom_service\&.Ocaml\&.coservice for others optional parameters\&. .sp .sp .I val post_coservice' : .B ?rt:'rt Eliom_service.rt -> .B ?name:string -> .B ?csrf_safe:bool -> .B ?csrf_scope:[< Eliom_common.user_scope ] -> .B ?csrf_secure:bool -> .B ?max_use:int -> .B ?timeout:float -> .B ?https:bool -> .B ?keep_nl_params:[ `All | `None | `Persistent ] -> .B ?keep_get_na_params:bool -> .B post_params:('post, [ `WithoutSuffix ], 'pn) Eliom_parameter.params_type -> .B unit -> .B (unit, 'post, [> `Nonattached of [> `Post ] Eliom_service.na_s ], .B [ `WithoutSuffix ], unit, 'pn, .B [< Eliom_service.registrable > `Registrable ], .B 'rt Eliom_service.ocaml_service) .B Eliom_service.service .sp The function .B post_coservice\&' ~post_params creates a taking .B post_params as POST parameters\&. .sp POST parameters couldn\&'t contain a suffix parameter\&. .sp If the optional parameter .B ~keep_get_na_params is .B 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\&. .sp See .B Eliom_service\&.Ocaml\&.service for a description of the optional .B ~https , .B ~rt and .B ~keep_nl_params parameters ; see .B Eliom_service\&.Ocaml\&.coservice for others optional parameters\&. .sp .sp .I val put_coservice' : .B ?rt:'rt Eliom_service.rt -> .B ?name:string -> .B ?csrf_safe:bool -> .B ?csrf_scope:[< Eliom_common.user_scope ] -> .B ?csrf_secure:bool -> .B ?max_use:int -> .B ?timeout:float -> .B ?https:bool -> .B ?keep_nl_params:[ `All | `None | `Persistent ] -> .B get_params:('get, [ `WithoutSuffix ], 'gn) Eliom_parameter.params_type -> .B unit -> .B ('get, Eliom_parameter.raw_post_data, .B [> `Nonattached of [> `Put ] Eliom_service.na_s ], [ `WithoutSuffix ], 'gn, .B Eliom_parameter.no_param_name, .B [< Eliom_service.registrable > `Registrable ], .B 'rt Eliom_service.ocaml_service) .B Eliom_service.service .sp The function .B put_coservice\&' ~get_params creates a taking a single POST parameter of type .B Eliom_parameter\&.raw_post_data \&. .sp See .B Eliom_service\&.Ocaml\&.service for a description of the optional .B ~https , .B ~rt and .B ~keep_nl_params parameters ; see .B Eliom_service\&.Ocaml\&.coservice for others optional parameters\&. .sp .sp .I val delete_coservice' : .B ?rt:'rt Eliom_service.rt -> .B ?name:string -> .B ?csrf_safe:bool -> .B ?csrf_scope:[< Eliom_common.user_scope ] -> .B ?csrf_secure:bool -> .B ?max_use:int -> .B ?timeout:float -> .B ?https:bool -> .B ?keep_nl_params:[ `All | `None | `Persistent ] -> .B get_params:('get, [ `WithoutSuffix ], 'gn) Eliom_parameter.params_type -> .B unit -> .B ('get, Eliom_parameter.raw_post_data, .B [> `Nonattached of [> `Delete ] Eliom_service.na_s ], [ `WithoutSuffix ], .B 'gn, Eliom_parameter.no_param_name, .B [< Eliom_service.registrable > `Registrable ], .B 'rt Eliom_service.ocaml_service) .B Eliom_service.service .sp The function .B delete_coservice\&' ~get_params creates a taking a single POST parameter of type .B Eliom_parameter\&.raw_post_data \&. .sp See .B Eliom_service\&.Ocaml\&.service for a description of the optional .B ~https , .B ~rt and .B ~keep_nl_params parameters ; see .B Eliom_service\&.Ocaml\&.coservice for others optional parameters\&. .sp .sp .I val external_service : .B prefix:string -> .B path:Eliom_lib.Url.path -> .B ?rt:'rt Eliom_service.rt -> .B ?keep_nl_params:[ `All | `None | `Persistent ] -> .B get_params:('get, [< Eliom_service.suff ] as 'a, 'gn) .B Eliom_parameter.params_type -> .B unit -> .B ('get, unit, [> `Attached of ([> `External ], [> `Get ]) Eliom_service.a_s ], .B 'a, 'gn, unit, [< Eliom_service.registrable > `Unregistrable ], .B 'rt Eliom_service.ocaml_service) .B Eliom_service.service .sp The function .B external_service ~prefix ~path ~get_params () creates a service for an external web site, that will use GET method and requires .B get_params as parameters\&. This allows one to creates links or forms towards other Web sites using Eliom\&'s syntax\&. .sp The parameter labelled .B ~path is the URL path\&. Each element of the list will be URL\-encoded\&. .sp The parameter labelled .B ~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\&. .sp 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\&. .sp See .B Eliom_service\&.Ocaml\&.service for a description of the optional .B ~keep_nl_params and .B ~rt parameters\&. .sp .sp .I val external_post_service : .B prefix:string -> .B path:Eliom_lib.Url.path -> .B ?rt:'rt Eliom_service.rt -> .B ?keep_nl_params:[ `All | `None | `Persistent ] -> .B get_params:('get, [< Eliom_service.suff ] as 'a, 'gn) .B Eliom_parameter.params_type -> .B post_params:('post, [ `WithoutSuffix ], 'pn) Eliom_parameter.params_type -> .B unit -> .B ('get, 'post, .B [> `Attached of ([> `External ], [> `Post ]) Eliom_service.a_s ], 'a, 'gn, .B 'pn, [< Eliom_service.registrable > `Unregistrable ], .B 'rt Eliom_service.ocaml_service) .B Eliom_service.service .sp Same as .B Eliom_service\&.Ocaml\&.external_service but with POST method\&. .sp .sp .I val external_put_service : .B prefix:string -> .B path:Eliom_lib.Url.path -> .B ?rt:'rt Eliom_service.rt -> .B ?keep_nl_params:[ `All | `None | `Persistent ] -> .B get_params:('get, [< Eliom_service.suff ] as 'a, 'gn) .B Eliom_parameter.params_type -> .B unit -> .B ('get, Eliom_parameter.raw_post_data, .B [> `Attached of ([> `External ], [> `Put ]) Eliom_service.a_s ], 'a, 'gn, .B Eliom_parameter.no_param_name, .B [< Eliom_service.registrable > `Unregistrable ], .B 'rt Eliom_service.ocaml_service) .B Eliom_service.service .sp Same as .B Eliom_service\&.Ocaml\&.external_service but with PUT method\&. .sp .sp .I val external_delete_service : .B prefix:string -> .B path:Eliom_lib.Url.path -> .B ?rt:'rt Eliom_service.rt -> .B ?keep_nl_params:[ `All | `None | `Persistent ] -> .B get_params:('get, [< Eliom_service.suff ] as 'a, 'gn) .B Eliom_parameter.params_type -> .B unit -> .B ('get, Eliom_parameter.raw_post_data, .B [> `Attached of ([> `External ], [> `Delete ]) Eliom_service.a_s ], 'a, 'gn, .B Eliom_parameter.no_param_name, .B [< Eliom_service.registrable > `Unregistrable ], .B 'rt Eliom_service.ocaml_service) .B Eliom_service.service .sp Same as .B Eliom_service\&.Ocaml\&.external_service but with DELETE method\&. .sp .sp