CivetServer.h 11 KB

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