Zen API

- Home
- Help Topics
- Types by Category
- All Types
- Files

All Classes Files Functions Variables Typedefs Macros Groups Pages
kHttpServer.h
Go to the documentation of this file.
1 /**
2 * @file kHttpServer.h
3 * @brief Declares the kHttpServer class.
4 *
5 * @internal
6 * Copyright (C) 2013-2014 by LMI Technologies Inc.
7 * Licensed under the MIT License.
8 * Redistributed files must retain the above copyright notice.
9 */
10 #ifndef K_API_HTTP_SERVER_H
11 #define K_API_HTTP_SERVER_H
12
13 #include <kApi/Io/kNetwork.h>
14
15 kBeginHeader()
16
17 /**
18 * @class kHttpServer
19 * @extends kObject
20 * @ingroup kApi-Io
21 * @brief Implements a simple HTTP server.
22 *
23 * The kHttpServer class implements a simple HTTP 1.1 server framework. The kHttpServer_SetHandler function
24 * can be used to register a callback function to process remote requests. The 'args' parameter to this callback
25 * receives a kHttpServerChannel instance, which can be used to access kHttpServerRequest and
26 * kHttpServerResponse objects. These request/response objects can be used to parse an incoming request
27 * and to format an outgoing response, respectively.
28 *
29 * kHttpServer uses a simple thread-per-connection model, where the maximum number of simultaneous connections
30 * can be configured using the kHttpServer_SetMaxConnections function. Accordingly, kHttpServer is better suited
31 * to small/embedded applications than large-scale web applications.
32 */
33 //typedef kObject kHttpServer; --forward-declared in kApiDef.x.h
34
35 /**
36 * Constructs a kHttpServer object.
37 *
38 * @public @memberof kHttpServer
39 * @param server Destination for the constructed object handle.
40 * @param allocator Memory allocator (or kNULL for default).
41 * @return Operation status.
42 */
43 kFx(kStatus) kHttpServer_Construct(kHttpServer* server, kAlloc allocator);
44
45 /**
46 * Sets the local address to which the server should bind.
47 *
48 * By default, the server will bind to the address returned by kIpAddress_AnyV4().
49 *
50 * This function can only be called while the server is stopped.
51 *
52 * @public @memberof kHttpServer
53 * @param server Server object.
54 * @param address IP address.
55 * @return Operation status.
56 */
57 kFx(kStatus) kHttpServer_SetAddress(kHttpServer server, kIpAddress address);
58
59 /**
60 * Sets the local port to which the server should bind.
61 *
62 * By default, the server will bind to port 80.
63 *
64 * This function can only be called while the server is stopped.
65 *
66 * @public @memberof kHttpServer
67 * @param server Server object.
68 * @param port Port number.
69 * @return Operation status.
70 */
71 kFx(kStatus) kHttpServer_SetPort(kHttpServer server, k32u port);
72
73 /**
74 * Sets the maximum number of simultaneous connections supported by the server.
75 *
76 * This function can only be called while the server is stopped.
77 *
78 * @public @memberof kHttpServer
79 * @param server Server object.
80 * @param capacity Maximum simultaneous connection count.
81 * @return Operation status.
82 */
83 kFx(kStatus) kHttpServer_SetMaxConnections(kHttpServer server, kSize capacity);
84
85 /**
86 * Sets the callback that will be invoked to process remote requests.
87 *
88 * The callback 'sender' argument will receive a kHttpServer instance, while the callback 'args' argument
89 * will receive a kHttpServerChannel instance. The callback receiver can use the kHttpServerChannel object to
90 * access kHttpServerRequest and kHttpServerResponse objects, which can be used to parse the incoming request
91 * and to generate a response.
92 *
93 * This function can only be called while the server is stopped.
94 *
95 * @public @memberof kHttpServer
96 * @param server Server object.
97 * @param function Callback function.
98 * @param receiver Callback receiver.
99 * @return Operation status.
100 */
101 kFx(kStatus) kHttpServer_SetHandler(kHttpServer server, kCallbackFx function, kPointer receiver);
102
103 /**
104 * Starts the server.
105 *
106 * @public @memberof kHttpServer
107 * @param server kHttpServer object.
108 * @return Operation status.
109 */
110 kFx(kStatus) kHttpServer_Start(kHttpServer server);
111
112 /**
113 * Stops the server.
114 *
115 * All asynchronous activities performed by the server will be stopped before this
116 * function returns.
117 *
118 * @public @memberof kHttpServer
119 * @param server kHttpServer object.
120 * @return Operation status.
121 */
122 kFx(kStatus) kHttpServer_Stop(kHttpServer server);
123
124 /**
125 * Reports the local end-point for a running server.
126 *
127 * @public @memberof kHttpServer
128 * @param server kHttpServer object.
129 * @param endPoint Receives local end-point information.
130 * @return Operation status.
131 */
132 kFx(kStatus) kHttpServer_LocalEndPoint(kHttpServer server, kIpEndPoint* endPoint);
133
134 kEndHeader()
135
136 #include <kApi/Io/kHttpServer.x.h>
137
138 #endif
k32u
Represents a 32-bit unsigned integer.
kCallbackFx
kStatus(kCall * kCallbackFx)(kPointer receiver, kPointer sender, void *args)
Callback signature for a generic event handler.
Definition: kApiDef.h:1030
kPointer
Represents a void pointer.
kSize
Represents an unsigned integer that can store a pointer address.
kAlloc
Abstract base class for memory allocator types.
kHttpServer::kHttpServer_LocalEndPoint
kStatus kHttpServer_LocalEndPoint(kHttpServer server, kIpEndPoint *endPoint)
Reports the local end-point for a running server.
kIpAddress
Represents an IP address.
Definition: kNetwork.h:36
kHttpServer::kHttpServer_Start
kStatus kHttpServer_Start(kHttpServer server)
Starts the server.
kHttpServer::kHttpServer_Construct
kStatus kHttpServer_Construct(kHttpServer *server, kAlloc allocator)
Constructs a kHttpServer object.
kHttpServer
Implements a simple HTTP server.
kHttpServer::kHttpServer_SetHandler
kStatus kHttpServer_SetHandler(kHttpServer server, kCallbackFx function, kPointer receiver)
Sets the callback that will be invoked to process remote requests.
kNetwork.h
IP networking definitions.
kStatus
Represents an enumeration of error codes.
kIpEndPoint
Represents an IP end point (address, port).
Definition: kNetwork.h:171
kHttpServer::kHttpServer_SetAddress
kStatus kHttpServer_SetAddress(kHttpServer server, kIpAddress address)
Sets the local address to which the server should bind.
kHttpServer::kHttpServer_Stop
kStatus kHttpServer_Stop(kHttpServer server)
Stops the server.
kHttpServer::kHttpServer_SetPort
kStatus kHttpServer_SetPort(kHttpServer server, k32u port)
Sets the local port to which the server should bind.
kHttpServer::kHttpServer_SetMaxConnections
kStatus kHttpServer_SetMaxConnections(kHttpServer server, kSize capacity)
Sets the maximum number of simultaneous connections supported by the server.