mongoose.h 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375
  1. // Copyright (c) 2004-2012 Sergey Lyubka
  2. //
  3. // Permission is hereby granted, free of charge, to any person obtaining a copy
  4. // of this software and associated documentation files (the "Software"), to deal
  5. // in the Software without restriction, including without limitation the rights
  6. // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  7. // copies of the Software, and to permit persons to whom the Software is
  8. // furnished to do so, subject to the following conditions:
  9. //
  10. // The above copyright notice and this permission notice shall be included in
  11. // all copies or substantial portions of the Software.
  12. //
  13. // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  14. // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  15. // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  16. // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  17. // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  18. // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  19. // THE SOFTWARE.
  20. #ifndef MONGOOSE_HEADER_INCLUDED
  21. #define MONGOOSE_HEADER_INCLUDED
  22. #include <stdio.h>
  23. #include <stddef.h>
  24. #ifdef __cplusplus
  25. extern "C" {
  26. #endif // __cplusplus
  27. struct mg_context; // Handle for the HTTP service itself
  28. struct mg_connection; // Handle for the individual connection
  29. // This structure contains information about the HTTP request.
  30. struct mg_request_info {
  31. const char *request_method; // "GET", "POST", etc
  32. const char *uri; // URL-decoded URI
  33. const char *http_version; // E.g. "1.0", "1.1"
  34. const char *query_string; // URL part after '?', not including '?', or NULL
  35. const char *remote_user; // Authenticated user, or NULL if no auth used
  36. long remote_ip; // Client's IP address
  37. int remote_port; // Client's port
  38. int is_ssl; // 1 if SSL-ed, 0 if not
  39. int num_headers; // Number of headers
  40. struct mg_header {
  41. const char *name; // HTTP header name
  42. const char *value; // HTTP header value
  43. } http_headers[64]; // Maximum 64 headers
  44. void *user_data; // User data pointer passed to mg_start()
  45. void *ev_data; // Event-specific data pointer
  46. };
  47. // Various events on which user-defined callback function is called by Mongoose.
  48. enum mg_event {
  49. // New HTTP request has arrived from the client.
  50. // If callback returns non-NULL, Mongoose stops handling current request.
  51. // ev_data contains NULL.
  52. MG_NEW_REQUEST,
  53. // Mongoose has finished handling the request.
  54. // Callback return value is ignored.
  55. // ev_data contains integer HTTP status code:
  56. // int http_reply_status_code = (long) request_info->ev_data;
  57. MG_REQUEST_COMPLETE,
  58. // HTTP error must be returned to the client.
  59. // If callback returns non-NULL, Mongoose stops handling error.
  60. // ev_data contains HTTP error code:
  61. // int http_reply_status_code = (long) request_info->ev_data;
  62. MG_HTTP_ERROR,
  63. // Mongoose logs a message.
  64. // If callback returns non-NULL, Mongoose stops handling that event.
  65. // ev_data contains a message to be logged:
  66. // const char *log_message = request_info->ev_data;
  67. MG_EVENT_LOG,
  68. // SSL initialization, sent before certificate setup.
  69. // If callback returns non-NULL, Mongoose does not set up certificates.
  70. // ev_data contains server's OpenSSL context:
  71. // SSL_CTX *ssl_context = request_info->ev_data;
  72. MG_INIT_SSL,
  73. // Sent on HTTP connect, before websocket handshake.
  74. // If user callback returns NULL, then mongoose proceeds
  75. // with handshake, otherwise it closes the connection.
  76. // ev_data contains NULL.
  77. MG_WEBSOCKET_CONNECT,
  78. // Handshake has been successfully completed.
  79. // Callback's return value is ignored.
  80. // ev_data contains NULL.
  81. MG_WEBSOCKET_READY,
  82. // Incoming message from the client, data could be read with mg_read().
  83. // If user callback returns non-NULL, mongoose closes the websocket.
  84. // ev_data contains NULL.
  85. MG_WEBSOCKET_MESSAGE,
  86. // Client has closed the connection.
  87. // Callback's return value is ignored.
  88. // ev_data contains NULL.
  89. MG_WEBSOCKET_CLOSE,
  90. // Mongoose tries to open file.
  91. // If callback returns non-NULL, Mongoose will not try to open it, but
  92. // will use the returned value as a pointer to the file data. This allows
  93. // for example to serve files from memory.
  94. // ev_data contains file path, including document root path.
  95. // Upon return, ev_data should return file size, which should be a long int.
  96. //
  97. // const char *file_name = request_info->ev_data;
  98. // if (strcmp(file_name, "foo.txt") == 0) {
  99. // request_info->ev_data = (void *) (long) 4;
  100. // return "data";
  101. // }
  102. // return NULL;
  103. //
  104. // Note that this even is sent multiple times during one request. Each
  105. // time mongoose tries to open or stat the file, this event is sent, e.g.
  106. // for opening .htpasswd file, stat-ting requested file, opening requested
  107. // file, etc.
  108. MG_OPEN_FILE,
  109. // Mongoose initializes Lua server page. Sent only if Lua support is enabled.
  110. // Callback's return value is ignored.
  111. // ev_data contains lua_State pointer.
  112. MG_INIT_LUA,
  113. // Mongoose has uploaded file to a temporary directory.
  114. // Callback's return value is ignored.
  115. // ev_data contains NUL-terminated file name.
  116. MG_UPLOAD,
  117. };
  118. // Prototype for the user-defined function. Mongoose calls this function
  119. // on every MG_* event.
  120. //
  121. // Parameters:
  122. // event: which event has been triggered.
  123. // conn: opaque connection handler. Could be used to read, write data to the
  124. // client, etc. See functions below that have "mg_connection *" arg.
  125. //
  126. // Return:
  127. // If handler returns non-NULL, that means that handler has processed the
  128. // request by sending appropriate HTTP reply to the client. Mongoose treats
  129. // the request as served.
  130. // If handler returns NULL, that means that handler has not processed
  131. // the request. Handler must not send any data to the client in this case.
  132. // Mongoose proceeds with request handling as if nothing happened.
  133. typedef void *(*mg_callback_t)(enum mg_event event, struct mg_connection *conn);
  134. // Start web server.
  135. //
  136. // Parameters:
  137. // callback: user defined event handling function or NULL.
  138. // options: NULL terminated list of option_name, option_value pairs that
  139. // specify Mongoose configuration parameters.
  140. //
  141. // Side-effects: on UNIX, ignores SIGCHLD and SIGPIPE signals. If custom
  142. // processing is required for these, signal handlers must be set up
  143. // after calling mg_start().
  144. //
  145. //
  146. // Example:
  147. // const char *options[] = {
  148. // "document_root", "/var/www",
  149. // "listening_ports", "80,443s",
  150. // NULL
  151. // };
  152. // struct mg_context *ctx = mg_start(&my_func, NULL, options);
  153. //
  154. // Please refer to http://code.google.com/p/mongoose/wiki/MongooseManual
  155. // for the list of valid option and their possible values.
  156. //
  157. // Return:
  158. // web server context, or NULL on error.
  159. struct mg_context *mg_start(mg_callback_t callback, void *user_data,
  160. const char **options);
  161. // Stop the web server.
  162. //
  163. // Must be called last, when an application wants to stop the web server and
  164. // release all associated resources. This function blocks until all Mongoose
  165. // threads are stopped. Context pointer becomes invalid.
  166. void mg_stop(struct mg_context *);
  167. // Get the value of particular configuration parameter.
  168. // The value returned is read-only. Mongoose does not allow changing
  169. // configuration at run time.
  170. // If given parameter name is not valid, NULL is returned. For valid
  171. // names, return value is guaranteed to be non-NULL. If parameter is not
  172. // set, zero-length string is returned.
  173. const char *mg_get_option(const struct mg_context *ctx, const char *name);
  174. // Return array of strings that represent valid configuration options.
  175. // For each option, a short name, long name, and default value is returned.
  176. // Array is NULL terminated.
  177. const char **mg_get_valid_option_names(void);
  178. // Add, edit or delete the entry in the passwords file.
  179. //
  180. // This function allows an application to manipulate .htpasswd files on the
  181. // fly by adding, deleting and changing user records. This is one of the
  182. // several ways of implementing authentication on the server side. For another,
  183. // cookie-based way please refer to the examples/chat.c in the source tree.
  184. //
  185. // If password is not NULL, entry is added (or modified if already exists).
  186. // If password is NULL, entry is deleted.
  187. //
  188. // Return:
  189. // 1 on success, 0 on error.
  190. int mg_modify_passwords_file(const char *passwords_file_name,
  191. const char *domain,
  192. const char *user,
  193. const char *password);
  194. // Return information associated with the request.
  195. struct mg_request_info *mg_get_request_info(struct mg_connection *);
  196. // Send data to the client.
  197. // Return:
  198. // 0 when the connection has been closed
  199. // -1 on error
  200. // number of bytes written on success
  201. int mg_write(struct mg_connection *, const void *buf, size_t len);
  202. #undef PRINTF_FORMAT_STRING
  203. #if _MSC_VER >= 1400
  204. #include <sal.h>
  205. #if _MSC_VER > 1400
  206. #define PRINTF_FORMAT_STRING(s) _Printf_format_string_ s
  207. #else
  208. #define PRINTF_FORMAT_STRING(s) __format_string s
  209. #endif
  210. #else
  211. #define PRINTF_FORMAT_STRING(s) s
  212. #endif
  213. #ifdef __GNUC__
  214. #define PRINTF_ARGS(x, y) __attribute__((format(printf, x, y)))
  215. #else
  216. #define PRINTF_ARGS(x, y)
  217. #endif
  218. // Send data to the browser using printf() semantics.
  219. //
  220. // Works exactly like mg_write(), but allows to do message formatting.
  221. // Below are the macros for enabling compiler-specific checks for
  222. // printf-like arguments.
  223. int mg_printf(struct mg_connection *,
  224. PRINTF_FORMAT_STRING(const char *fmt), ...) PRINTF_ARGS(2, 3);
  225. // Send contents of the entire file together with HTTP headers.
  226. void mg_send_file(struct mg_connection *conn, const char *path);
  227. // Read data from the remote end, return number of bytes read.
  228. int mg_read(struct mg_connection *, void *buf, size_t len);
  229. // Get the value of particular HTTP header.
  230. //
  231. // This is a helper function. It traverses request_info->http_headers array,
  232. // and if the header is present in the array, returns its value. If it is
  233. // not present, NULL is returned.
  234. const char *mg_get_header(const struct mg_connection *, const char *name);
  235. // Get a value of particular form variable.
  236. //
  237. // Parameters:
  238. // data: pointer to form-uri-encoded buffer. This could be either POST data,
  239. // or request_info.query_string.
  240. // data_len: length of the encoded data.
  241. // var_name: variable name to decode from the buffer
  242. // dst: destination buffer for the decoded variable
  243. // dst_len: length of the destination buffer
  244. //
  245. // Return:
  246. // On success, length of the decoded variable.
  247. // On error:
  248. // -1 (variable not found).
  249. // -2 (destination buffer is NULL, zero length or too small to hold the decoded variable).
  250. //
  251. // Destination buffer is guaranteed to be '\0' - terminated if it is not
  252. // NULL or zero length.
  253. int mg_get_var(const char *data, size_t data_len,
  254. const char *var_name, char *dst, size_t dst_len);
  255. // Fetch value of certain cookie variable into the destination buffer.
  256. //
  257. // Destination buffer is guaranteed to be '\0' - terminated. In case of
  258. // failure, dst[0] == '\0'. Note that RFC allows many occurrences of the same
  259. // parameter. This function returns only first occurrence.
  260. //
  261. // Return:
  262. // On success, value length.
  263. // On error:
  264. // -1 (either "Cookie:" header is not present at all or the requested parameter is not found).
  265. // -2 (destination buffer is NULL, zero length or too small to hold the value).
  266. int mg_get_cookie(const struct mg_connection *,
  267. const char *cookie_name, char *buf, size_t buf_len);
  268. // Download data from the remote web server.
  269. // host: host name to connect to, e.g. "foo.com", or "10.12.40.1".
  270. // port: port number, e.g. 80.
  271. // use_ssl: wether to use SSL connection.
  272. // error_buffer, error_buffer_size: error message placeholder.
  273. // request_fmt,...: HTTP request.
  274. // Return:
  275. // On success, valid pointer to the new connection, suitable for mg_read().
  276. // On error, NULL.
  277. // Example:
  278. // char ebuf[100];
  279. // struct mg_connection *conn;
  280. // conn = mg_download("google.com", 80, 0, ebuf, sizeof(ebuf),
  281. // "%s", "GET / HTTP/1.0\r\nHost: google.com\r\n\r\n");
  282. struct mg_connection *mg_download(const char *host, int port, int use_ssl,
  283. char *error_buffer, size_t error_buffer_size,
  284. const char *request_fmt, ...);
  285. // Close the connection opened by mg_download().
  286. void mg_close_connection(struct mg_connection *conn);
  287. // File upload functionality. Each uploaded file gets saved into a temporary
  288. // file and MG_UPLOAD event is sent.
  289. // Return number of uploaded files.
  290. int mg_upload(struct mg_connection *conn, const char *destination_dir);
  291. // Convenience function -- create detached thread.
  292. // Return: 0 on success, non-0 on error.
  293. typedef void * (*mg_thread_func_t)(void *);
  294. int mg_start_thread(mg_thread_func_t f, void *p);
  295. // Return builtin mime type for the given file name.
  296. // For unrecognized extensions, "text/plain" is returned.
  297. const char *mg_get_builtin_mime_type(const char *file_name);
  298. // Return Mongoose version.
  299. const char *mg_version(void);
  300. // MD5 hash given strings.
  301. // Buffer 'buf' must be 33 bytes long. Varargs is a NULL terminated list of
  302. // ASCIIz strings. When function returns, buf will contain human-readable
  303. // MD5 hash. Example:
  304. // char buf[33];
  305. // mg_md5(buf, "aa", "bb", NULL);
  306. void mg_md5(char buf[33], ...);
  307. #ifdef __cplusplus
  308. }
  309. #endif // __cplusplus
  310. #endif // MONGOOSE_HEADER_INCLUDED