From e597c44ff938a45dcbf74f460425b02513cfe4cf Mon Sep 17 00:00:00 2001 From: Stefano Zacchiroli Date: Mon, 3 Feb 2003 20:37:26 +0000 Subject: [PATCH] - removed superseded exceptions: Unsupported_method, Unsupported_HTTP_version - added a lot of ocamldoc comments --- helm/DEVEL/ocaml-http/http_types.ml | 147 ++++++++++++++++++++++++++-- 1 file changed, 140 insertions(+), 7 deletions(-) diff --git a/helm/DEVEL/ocaml-http/http_types.ml b/helm/DEVEL/ocaml-http/http_types.ml index 34c8481a7..cae9998b3 100644 --- a/helm/DEVEL/ocaml-http/http_types.ml +++ b/helm/DEVEL/ocaml-http/http_types.ml @@ -19,6 +19,8 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA *) +(** Type definitions *) + (** HTTP version, actually only 1.0 and 1.1 are supported. Note that 'supported' here means only 'accepted inside a HTTP request line', no different behaviours are actually implemented depending on HTTP version *) @@ -41,16 +43,24 @@ type meth = then exit, threads can communicate using standard OCaml Thread library. *) type daemon_mode = [ `Single | `Fork | `Thread ] + (** A TCP server is a function taking an address on which bind and listen for + connections, an optional timeout after which abort client connections and a + callback function which in turn takes an input and an output channel as + arguments. After receiving this argument a TCP server sits and waits for + connection, on each connection it apply the callback function to channels + connected to client. *) type tcp_server = sockaddr:Unix.sockaddr -> timeout:int option -> (in_channel -> out_channel -> unit) -> unit + (** informational HTTP status, see RFC2616 *) type informational_substatus = [ `Continue | `Switching_protocols ] + (** success HTTP status, see RFC2616 *) type success_substatus = [ `OK | `Created @@ -61,6 +71,7 @@ type success_substatus = | `Partial_content ] + (** redirection HTTP status, see RFC2616 *) type redirection_substatus = [ `Multiple_choices | `Moved_permanently @@ -71,6 +82,7 @@ type redirection_substatus = | `Temporary_redirect ] + (** client error HTTP status, see RFC2616 *) type client_error_substatus = [ `Bad_request | `Unauthorized @@ -92,6 +104,7 @@ type client_error_substatus = | `Expectation_failed ] + (** server error HTTP status, see RFC2616 *) type server_error_substatus = [ `Internal_server_error | `Not_implemented @@ -112,6 +125,7 @@ type error_status = | server_error_status ] + (** HTTP status *) type status = [ informational_status | success_status @@ -120,31 +134,58 @@ type status = | server_error_status ] + (** {2 Exceptions} *) + + (** invalid header encountered *) exception Invalid_header of string + + (** invalid header name encountered *) exception Invalid_header_name of string + + (** invalid header value encountered *) exception Invalid_header_value of string + + (** unsupported or invalid HTTP version encountered *) exception Invalid_HTTP_version of string + + (** unsupported or invalid HTTP method encountered *) exception Invalid_HTTP_method of string + + (** invalid HTTP status code integer representation encountered *) exception Invalid_code of int -exception Invalid_status of status + (** invalid URL encountered *) exception Malformed_URL of string + + (** invalid query string encountered *) exception Malformed_query of string + + (** invalid query string part encountered, arguments are parameter name and + parameter value *) exception Malformed_query_part of string * string -exception Unsupported_method of string -exception Unsupported_HTTP_version of string + + (** invalid request URI encountered *) exception Malformed_request_URI of string + + (** malformed request received *) exception Malformed_request of string + (** a parameter you were looking for was not found *) exception Param_not_found of string + (** invalid HTTP status line encountered *) exception Invalid_status_line of string + + (** an header you were looking for was not found *) exception Header_not_found of string (** raisable by callback functions to make main daemon quit, this is the only 'clean' way to make start functions return *) exception Quit + (** {2 OO representation of HTTP messages} *) + + (** HTTP generic messages. See {! Http_message.message} *) class type message = object method version: version option @@ -157,10 +198,6 @@ class type message = object method addBody: string -> unit method addBodyBuf: Buffer.t -> unit - (** header name comparison are performed in a case-insensitive manner as - required by RFC2616, actually the implementation works converting all header - names in lowercase *) - method addHeader: name:string -> value:string -> unit method addHeaders: (string * string) list -> unit method replaceHeader: name:string -> value:string -> unit @@ -183,65 +220,161 @@ class type message = object end + (** HTTP requests *) class type request = object + (** an HTTP request is a flavour of HTTP message *) inherit message + (** @return request method *) method meth: meth + + (** @return requested URI (including query string, fragment, ...) *) method uri: string + + (** @return requested path *) method path: string + + (** lookup a given parameter + @param meth if given restrict the lookup area (e.g. if meth = POST than + only parameters received via POST are searched), if not given both GET and + POST parameter are searched in an unspecified order (actually the + implementation prefers POST parameters but this is not granted, you've + been warned) + @param name name of the parameter to lookup + @return value associated to parameter name + @raise Param_not_found if parameter name was not found *) method param: ?meth:meth -> string -> string + + (** like param above but return a list of values associated to given + parameter (a parameter could be defined indeed more than once: passed more + than once in a query string or passed both insider the url (the GET way) + and inside message body (the POST way)) *) method paramAll: ?meth:meth -> string -> string list + + (** @return the list of all received parameters *) method params: (string * string) list + + (** @return the list of all parameters received via GET *) method params_GET: (string * string) list + + (** @return the list of all parameter received via POST *) method params_POST: (string * string) list end + (** HTTP responses *) class type response = object inherit message + (** @return response code *) method code: int + + (** set response code *) method setCode: int -> unit + + (** @return response status, see {! Http_types.status} *) method status: status + + (** set response status *) method setStatus: status -> unit + + (** @return reason string *) method reason: string + + (** set reason string *) method setReason: string -> unit + + (** @return status line *) method statusLine: string + + (** set status line + @raise Invalid_status_line if an invalid HTTP status line was passed *) method setStatusLine: string -> unit + (** response is an informational one *) method isInformational: bool + + (** response is a success one *) method isSuccess: bool + + (** response is a redirection one *) method isRedirection: bool + + (** response is a client error one *) method isClientError: bool + + (** response is a server error one *) method isServerError: bool + + (** response is either a client error or a server error response *) method isError: bool + (** add basic headers to response, see {! Http_daemon.send_basic_headers} + *) method addBasicHeaders: unit + + (** facilities to access some frequently used headers *) + + (** @return Content-Type header value *) method contentType: string + + (** set Content-Type header value *) method setContentType: string -> unit + + (** @return Content-Encoding header value *) method contentEncoding: string + + (** set Content-Encoding header value *) method setContentEncoding: string -> unit + + (** @return Date header value *) method date: string + + (** set Date header value *) method setDate: string -> unit + + (** @return Expires header value *) method expires: string + + (** set Expires header value *) method setExpires: string -> unit + + (** @return Server header value *) method server: string + + (** set Server header value *) method setServer: string -> unit end + (** {2 OO representation of other HTTP "entities"} *) + + (** an HTTP connection from a client to a server *) class type connection = object + (** @return next request object, may block if client hasn't submitted any + request yet, may be None if client request was ill-formed *) method getRequest: request option + + (** respond to client sending it a response *) method respond_with: response -> unit + + (** close connection to client. Warning: this object can't be used any + longer after this method has been called *) method close: unit end + (** an HTTP daemon *) class type daemon = object + (** @return a connection to a client, may block if no client has connected + yet *) method accept: connection + + (** shortcut method, blocks until a client has submit a request and + return a pair request * connection *) method getRequest: request * connection end -- 2.39.2