Jamoma API  0.6.0.a19
CivetServer.h
1 /*
2  * Copyright (c) 2013 No Face Press, LLC
3  * License http://opensource.org/licenses/mit-license.php MIT License
4  */
5 
6 #ifndef _CIVETWEB_SERVER_H_
7 #define _CIVETWEB_SERVER_H_
8 #ifdef __cplusplus
9 
10 #include "civetweb.h"
11 #include <vector>
12 #include <string>
13 
14 class CivetServer; // forward declaration
15 
16 /**
17  * Basic interface for a URI request handler. Handlers implementations
18  * must be reentrant.
19  */
20 class CivetHandler
21 {
22 public:
23 
24  /**
25  * Destructor
26  */
27  virtual ~CivetHandler() {
28  }
29 
30  /**
31  * Callback method for GET request.
32  *
33  * @param server - the calling server
34  * @param conn - the connection information
35  * @returns true if implemented, false otherwise
36  */
37  virtual bool handleGet(CivetServer *server, struct mg_connection *conn);
38 
39  /**
40  * Callback method for POST request.
41  *
42  * @param server - the calling server
43  * @param conn - the connection information
44  * @returns true if implemented, false otherwise
45  */
46  virtual bool handlePost(CivetServer *server, struct mg_connection *conn);
47 
48  /**
49  * Callback method for PUT request.
50  *
51  * @param server - the calling server
52  * @param conn - the connection information
53  * @returns true if implemented, false otherwise
54  */
55  virtual bool handlePut(CivetServer *server, struct mg_connection *conn);
56 
57  /**
58  * Callback method for DELETE request.
59  *
60  * @param server - the calling server
61  * @param conn - the connection information
62  * @returns true if implemented, false otherwise
63  */
64  virtual bool handleDelete(CivetServer *server, struct mg_connection *conn);
65 
66 };
67 
68 /**
69  * CivetServer
70  *
71  * Basic class for embedded web server. This has a URL mapping built-in.
72  */
73 class CivetServer
74 {
75 public:
76 
77  /**
78  * Constructor
79  *
80  * This automatically starts the sever.
81  * It is good practice to call getContext() after this in case there
82  * were errors starting the server.
83  *
84  * @param options - the web server options.
85  * @param callbacks - optional web server callback methods.
86  */
87  CivetServer(const char **options, const struct mg_callbacks *callbacks = 0);
88 
89  /**
90  * Destructor
91  */
92  virtual ~CivetServer();
93 
94  /**
95  * close()
96  *
97  * Stops server and frees resources.
98  */
99  void close();
100 
101  /**
102  * getContext()
103  *
104  * @return the context or 0 if not running.
105  */
106  const struct mg_context *getContext() const {
107  return context;
108  }
109 
110  /**
111  * addHandler(const std::string &, CivetHandler *)
112  *
113  * Adds a URI handler. If there is existing URI handler, it will
114  * be replaced with this one.
115  *
116  * URI's are ordered and prefix (REST) URI's are supported.
117  *
118  * @param uri - URI to match.
119  * @param handler - handler instance to use. This will be free'ed
120  * when the server closes and instances cannot be reused.
121  */
122  void addHandler(const std::string &uri, CivetHandler *handler);
123 
124  /**
125  * removeHandler(const std::string &)
126  *
127  * Removes a handler.
128  *
129  * @param - the exact URL used in addHandler().
130  */
131  void removeHandler(const std::string &uri);
132 
133  /**
134  * getCookie(struct mg_connection *conn, const std::string &cookieName, std::string &cookieValue)
135  * @param conn - the connection information
136  * @param cookieName - cookie name to get the value from
137  * @param cookieValue - cookie value is returned using thiis reference
138  * @puts the cookie value string that matches the cookie name in the _cookieValue string.
139  * @returns the size of the cookie value string read.
140  */
141  static int getCookie(struct mg_connection *conn, const std::string &cookieName, std::string &cookieValue);
142 
143  /**
144  * getHeader(struct mg_connection *conn, const std::string &headerName)
145  * @param conn - the connection information
146  * @param headerName - header name to get the value from
147  * @returns a char array whcih contains the header value as string
148  */
149  static const char* getHeader(struct mg_connection *conn, const std::string &headerName);
150 
151  /**
152  * getParam(struct mg_connection *conn, const char *, std::string &, size_t)
153  *
154  * Returns a query paramter contained in the supplied buffer. The
155  * occurance value is a zero-based index of a particular key name. This
156  * should nto be confused with the index over all of the keys.
157  *
158  * @param data the query string
159  * @param name the key to search for
160  * @param the destination string
161  * @param occurrence the occurrence of the selected name in the query (0 based).
162  * @return true of key was found
163  */
164  static bool getParam(struct mg_connection *conn, const char *name,
165  std::string &dst, size_t occurrence=0);
166 
167  /**
168  * getParam(const std::string &, const char *, std::string &, size_t)
169  *
170  * Returns a query paramter contained in the supplied buffer. The
171  * occurance value is a zero-based index of a particular key name. This
172  * should nto be confused with the index over all of the keys.
173  *
174  * @param data the query string
175  * @param name the key to search for
176  * @param the destination string
177  * @param occurrence the occurrence of the selected name in the query (0 based).
178  * @return true of key was found
179  */
180  static bool getParam(const std::string &data, const char *name,
181  std::string &dst, size_t occurrence=0) {
182  return getParam(data.c_str(), data.length(), name, dst, occurrence);
183  }
184 
185  /**
186  * getParam(const char *, size_t, const char *, std::string &, size_t)
187  *
188  * Returns a query paramter contained in the supplied buffer. The
189  * occurance value is a zero-based index of a particular key name. This
190  * should nto be confused with the index over all of the keys.
191  *
192  * @param data the query string
193  * @param length length of the query string
194  * @param name the key to search for
195  * @param the destination string
196  * @param occurrence the occurrence of the selected name in the query (0 based).
197  * @return true of key was found
198  */
199  static bool getParam(const char *data, size_t data_len, const char *name,
200  std::string &dst, size_t occurrence=0);
201 
202 
203  /**
204  * urlDecode(const std::string &, std::string &, bool)
205  *
206  * @param src string to be decoded
207  * @param dst destination string
208  * @is_form_url_encoded true if form url encoded
209  * form-url-encoded data differs from URI encoding in a way that it
210  * uses '+' as character for space, see RFC 1866 section 8.2.1
211  * http://ftp.ics.uci.edu/pub/ietf/html/rfc1866.txt
212  */
213  static void urlDecode(const std::string &src, std::string &dst, bool is_form_url_encoded=true) {
214  urlDecode(src.c_str(), src.length(), dst, is_form_url_encoded);
215  }
216 
217  /**
218  * urlDecode(const char *, size_t, std::string &, bool)
219  *
220  * @param src buffer to be decoded
221  * @param src_len length of buffer to be decoded
222  * @param dst destination string
223  * @is_form_url_encoded true if form url encoded
224  * form-url-encoded data differs from URI encoding in a way that it
225  * uses '+' as character for space, see RFC 1866 section 8.2.1
226  * http://ftp.ics.uci.edu/pub/ietf/html/rfc1866.txt
227  */
228  static void urlDecode(const char *src, size_t src_len, std::string &dst, bool is_form_url_encoded=true);
229 
230  /**
231  * urlDecode(const char *, std::string &, bool)
232  *
233  * @param src buffer to be decoded (0 terminated)
234  * @param dst destination string
235  * @is_form_url_encoded true if form url encoded
236  * form-url-encoded data differs from URI encoding in a way that it
237  * uses '+' as character for space, see RFC 1866 section 8.2.1
238  * http://ftp.ics.uci.edu/pub/ietf/html/rfc1866.txt
239  */
240  static void urlDecode(const char *src, std::string &dst, bool is_form_url_encoded=true);
241 
242  /**
243  * urlEncode(const std::string &, std::string &, bool)
244  *
245  * @param src buffer to be encoded
246  * @param dst destination string
247  * @append true if string should not be cleared before encoding.
248  */
249  static void urlEncode(const std::string &src, std::string &dst, bool append=false) {
250  urlEncode(src.c_str(), src.length(), dst, append);
251  }
252 
253  /**
254  * urlEncode(const char *, size_t, std::string &, bool)
255  *
256  * @param src buffer to be encoded (0 terminated)
257  * @param dst destination string
258  * @append true if string should not be cleared before encoding.
259  */
260  static void urlEncode(const char *src, std::string &dst, bool append=false);
261 
262  /**
263  * urlEncode(const char *, size_t, std::string &, bool)
264  *
265  * @param src buffer to be encoded
266  * @param src_len length of buffer to be decoded
267  * @param dst destination string
268  * @append true if string should not be cleared before encoding.
269  */
270  static void urlEncode(const char *src, size_t src_len, std::string &dst, bool append=false);
271 
272 protected:
273 
274  struct mg_context *context;
275 
276 private:
277  /**
278  * requestHandler(struct mg_connection *, void *cbdata)
279  *
280  * Handles the incomming request.
281  *
282  * @param conn - the connection information
283  * @param cbdata - pointer to the CivetHandler instance.
284  * @returns 0 if implemented, false otherwise
285  */
286  static int requestHandler(struct mg_connection *conn, void *cbdata);
287 
288 };
289 
290 #endif /* __cplusplus */
291 #endif /* _CIVETWEB_SERVER_H_ */