@@ -5,13 +5,98 @@ HTTP Server API
55General
66-------
77
8- .. FIXME describe the general API for the HTTP Servers
8+ :mod: `cpp-netlib ` includes and implements two distinct HTTP server
9+ implementations that you can use and embed in your own applications. Both HTTP
10+ Server implementations:
11+
12+ * **Cannot be copied. ** This means you may have to store instances of the HTTP
13+ Server in dynamic memory if you intend to use them as function parameters or
14+ pass them around in smart pointers of by reference.
15+ * **Assume that requests made are independent of each other. ** None of the
16+ HTTP Server implementations support request pipelining (yet) so a single
17+ connection only deals with a single request.
18+ * **Are header-only and are compiled-into your application. ** Future releases
19+ in case you want to upgrade the implementation you are using in your
20+ application will be distributed as header-only implementations, which means
21+ you have to re-compile your application to use a newer version of the
22+ implementations.
23+
24+ The HTTP Servers have different semantics, and in some cases require different
25+ APIs from the supplied template parameters.
926
1027Implementations
1128---------------
1229
13- .. FIXME describe the internal implementation, with diagrams if at all possible
14- and within reasonable efforts.
30+ There are two different user-facing template classes that differentiate the
31+ `Synchronous Servers `_ from the `Asynchronous Servers `_. Both templates take a
32+ single template parameter named ``Handler `` which describes the type of the
33+ Handler function object.
34+
35+ There are two different Handler concepts, one concept for `Synchronous Servers `_
36+ and another for `Asynchronous Servers `.
37+
38+ The SynchronusHandler concept for `Synchronous Servers `_ is described by the
39+ following table:
40+
41+ ---------------
42+
43+ **Legend: **
44+
45+ H
46+ The Handler type.
47+ h
48+ An instance of H.
49+ Req
50+ A type that models the Request Concept.
51+ Res
52+ A type that models the Response Concept.
53+ req
54+ An instance of Req.
55+ res
56+ An instance of Res.
57+
58+ +----------------+-------------+----------------------------------------------+
59+ | Construct| Return Type| Description|
60+ +================+=============+==============================================+
61+ | ``h(req,res) ``| ``void ``| Handle the request; res is passed in as a|
62+ | | | non-const lvalue, which represents the|
63+ | | | response to be returned to the client|
64+ | | | performing the request.|
65+ +----------------+-------------+----------------------------------------------+
66+
67+ More information about the internals of the `Synchronous Servers `_ can be found
68+ in the following section.
69+
70+ The AsynchronousHandler concept for `Asynchronous Servers `_ is described by the
71+ following table:
72+
73+ ---------------
74+
75+ **Legend: **
76+
77+ H
78+ The Handler type.
79+ h
80+ An instance of H.
81+ Req
82+ A type that models the Request Concept.
83+ ConnectionPtr
84+ A type that models the Connection Pointer Concept.
85+ req
86+ An instance of Req.
87+ conn
88+ An instance of ConncetionPtr.
89+
90+ +------------------+-------------+--------------------------------------------+
91+ | Construct| Return Type| Description|
92+ +==================+=============+============================================+
93+ | ``h(req, conn) ``| ``void ``| Handle the request; conn is a shared|
94+ | | | pointer which exposes functions for|
95+ | | | writing to and reading from the connection.|
96+ +------------------+-------------+--------------------------------------------+
97+
98+ More information about the internals of the `Asynchronous Servers `_ can be found
99+ in the following section.
15100
16101Synchronous Servers
17102~~~~~~~~~~~~~~~~~~~