From 76364af243530f3ca52cac78c869a66d58f20ace Mon Sep 17 00:00:00 2001 From: Deomid Ryabkov Date: Mon, 11 Apr 2016 12:40:19 +0300 Subject: [PATCH] Fix comment format in http.h Functions decl must follow comment to be correctly documented PUBLISHED_FROM=6ab035cda470c2c23240db4435abd8c241c71b0d --- docs/c-api/http.h/items.json | 28 +++++++++++++ docs/c-api/http.h/mg_connect_http.md | 35 +++++++++++++++++ docs/c-api/http.h/mg_connect_http_opt.md | 18 +++++++++ docs/c-api/http.h/mg_connect_ws.md | 30 ++++++++++++++ docs/c-api/http.h/mg_connect_ws_opt.md | 17 ++++++++ docs/c-api/http.h/mg_file_upload_handler.md | 39 +++++++++++++++++++ docs/c-api/http.h/mg_fu_fname_fn.md | 11 ++++++ .../c-api/http.h/mg_register_http_endpoint.md | 35 +++++++++++++++++ mongoose.h | 14 +++---- 9 files changed, 219 insertions(+), 8 deletions(-) create mode 100644 docs/c-api/http.h/mg_connect_http.md create mode 100644 docs/c-api/http.h/mg_connect_http_opt.md create mode 100644 docs/c-api/http.h/mg_connect_ws.md create mode 100644 docs/c-api/http.h/mg_connect_ws_opt.md create mode 100644 docs/c-api/http.h/mg_file_upload_handler.md create mode 100644 docs/c-api/http.h/mg_fu_fname_fn.md create mode 100644 docs/c-api/http.h/mg_register_http_endpoint.md diff --git a/docs/c-api/http.h/items.json b/docs/c-api/http.h/items.json index 01032204..a8bd24e0 100644 --- a/docs/c-api/http.h/items.json +++ b/docs/c-api/http.h/items.json @@ -16,6 +16,14 @@ "type": "markdown", "name": "mg_send_websocket_handshake2.md" }, + { + "type": "markdown", + "name": "mg_connect_ws.md" + }, + { + "type": "markdown", + "name": "mg_connect_ws_opt.md" + }, { "type": "markdown", "name": "mg_send_websocket_frame.md" @@ -76,10 +84,30 @@ "type": "markdown", "name": "mg_http_create_digest_auth_header.md" }, + { + "type": "markdown", + "name": "mg_connect_http.md" + }, + { + "type": "markdown", + "name": "mg_connect_http_opt.md" + }, { "type": "markdown", "name": "mg_serve_http.md" }, + { + "type": "markdown", + "name": "mg_register_http_endpoint.md" + }, + { + "type": "markdown", + "name": "mg_file_upload_handler.md" + }, + { + "type": "markdown", + "name": "mg_fu_fname_fn.md" + }, { "type": "markdown", "name": "struct_http_message.md" diff --git a/docs/c-api/http.h/mg_connect_http.md b/docs/c-api/http.h/mg_connect_http.md new file mode 100644 index 00000000..b897be0c --- /dev/null +++ b/docs/c-api/http.h/mg_connect_http.md @@ -0,0 +1,35 @@ +--- +title: "mg_connect_http()" +decl_name: "mg_connect_http" +symbol_kind: "func" +signature: | + struct mg_connection *mg_connect_http(struct mg_mgr *mgr, + mg_event_handler_t event_handler, + const char *url, + const char *extra_headers, + const char *post_data); +--- + +Helper function that creates outbound HTTP connection. + +`url` is a URL to fetch. It must be properly URL-encoded, e.g. have +no spaces, etc. By default, `mg_connect_http()` sends Connection and +Host headers. `extra_headers` is an extra HTTP headers to send, e.g. +`"User-Agent: my-app\r\n"`. +If `post_data` is NULL, then GET request is created. Otherwise, POST request +is created with the specified POST data. Note that if the data being posted +is a form submission, the `Content-Type` header should be set accordingly +(see example below). + +Examples: + +```c + nc1 = mg_connect_http(mgr, ev_handler_1, "http://www.google.com", NULL, + NULL); + nc2 = mg_connect_http(mgr, ev_handler_1, "https://github.com", NULL, NULL); + nc3 = mg_connect_http( + mgr, ev_handler_1, "my_server:8000/form_submit/", + "Content-Type: application/x-www-form-urlencoded\r\n", + "var_1=value_1&var_2=value_2"); +``` + diff --git a/docs/c-api/http.h/mg_connect_http_opt.md b/docs/c-api/http.h/mg_connect_http_opt.md new file mode 100644 index 00000000..be68a67f --- /dev/null +++ b/docs/c-api/http.h/mg_connect_http_opt.md @@ -0,0 +1,18 @@ +--- +title: "mg_connect_http_opt()" +decl_name: "mg_connect_http_opt" +symbol_kind: "func" +signature: | + struct mg_connection *mg_connect_http_opt(struct mg_mgr *mgr, + mg_event_handler_t ev_handler, + struct mg_connect_opts opts, + const char *url, + const char *extra_headers, + const char *post_data); +--- + +Helper function that creates outbound HTTP connection. + +Mostly identical to mg_connect_http, but allows to provide extra parameters +(for example, SSL parameters + diff --git a/docs/c-api/http.h/mg_connect_ws.md b/docs/c-api/http.h/mg_connect_ws.md new file mode 100644 index 00000000..417279c8 --- /dev/null +++ b/docs/c-api/http.h/mg_connect_ws.md @@ -0,0 +1,30 @@ +--- +title: "mg_connect_ws()" +decl_name: "mg_connect_ws" +symbol_kind: "func" +signature: | + struct mg_connection *mg_connect_ws(struct mg_mgr *mgr, + mg_event_handler_t event_handler, + const char *url, const char *protocol, + const char *extra_headers); +--- + +Helper function that creates an outbound WebSocket connection. + +`url` is a URL to connect to. It must be properly URL-encoded, e.g. have +no spaces, etc. By default, `mg_connect_ws()` sends Connection and +Host headers. `extra_headers` is an extra HTTP headers to send, e.g. +`"User-Agent: my-app\r\n"`. +If `protocol` is not NULL, then a `Sec-WebSocket-Protocol` header is sent. + +Examples: + +```c + nc1 = mg_connect_ws(mgr, ev_handler_1, "ws://echo.websocket.org", NULL, + NULL); + nc2 = mg_connect_ws(mgr, ev_handler_1, "wss://echo.websocket.org", NULL, + NULL); + nc3 = mg_connect_ws(mgr, ev_handler_1, "ws://api.cesanta.com", + "clubby.cesanta.com", NULL); +``` + diff --git a/docs/c-api/http.h/mg_connect_ws_opt.md b/docs/c-api/http.h/mg_connect_ws_opt.md new file mode 100644 index 00000000..3ab91083 --- /dev/null +++ b/docs/c-api/http.h/mg_connect_ws_opt.md @@ -0,0 +1,17 @@ +--- +title: "mg_connect_ws_opt()" +decl_name: "mg_connect_ws_opt" +symbol_kind: "func" +signature: | + struct mg_connection *mg_connect_ws_opt(struct mg_mgr *mgr, + mg_event_handler_t ev_handler, + struct mg_connect_opts opts, + const char *url, const char *protocol, + const char *extra_headers); +--- + +Helper function that creates an outbound WebSocket connection + +Mostly identical to mg_connect_ws, but allows to provide extra parameters +(for example, SSL parameters + diff --git a/docs/c-api/http.h/mg_file_upload_handler.md b/docs/c-api/http.h/mg_file_upload_handler.md new file mode 100644 index 00000000..b0459676 --- /dev/null +++ b/docs/c-api/http.h/mg_file_upload_handler.md @@ -0,0 +1,39 @@ +--- +title: "mg_file_upload_handler()" +decl_name: "mg_file_upload_handler" +symbol_kind: "func" +signature: | + void mg_file_upload_handler(struct mg_connection *nc, int ev, void *ev_data, + mg_fu_fname_fn local_name_fn); +--- + +File upload handler. +This handler can be used to implement file uploads with minimum code. +This handler will process MG_EV_HTTP_PART_* events and store file data into +a local file. +`local_name_fn` will be invoked with whatever name was provided by the client +and will expect the name of the local file to open. Return value of NULL will +abort file upload (client will get a "403 Forbidden" response). If non-null, +the returned string must be heap-allocated and will be freed by the caller. +Exception: it is ok to return the same string verbatim. + +Example: + +```c +struct mg_str upload_fname(struct mg_connection *nc, struct mg_str fname) { + // Just return the same filename. Do not actually do this except in test! + // fname is user-controlled and needs to be sanitized. + return fname; +} +void ev_handler(struct mg_connection *nc, int ev, void *ev_data) { + switch (ev) { + ... + case MG_EV_HTTP_PART_BEGIN: + case MG_EV_HTTP_PART_DATA: + case MG_EV_HTTP_PART_END: + mg_file_upload_handler(nc, ev, ev_data, upload_fname); + break; + } +} +``` + diff --git a/docs/c-api/http.h/mg_fu_fname_fn.md b/docs/c-api/http.h/mg_fu_fname_fn.md new file mode 100644 index 00000000..78aa7c8b --- /dev/null +++ b/docs/c-api/http.h/mg_fu_fname_fn.md @@ -0,0 +1,11 @@ +--- +title: "mg_fu_fname_fn" +decl_name: "mg_fu_fname_fn" +symbol_kind: "typedef" +signature: | + typedef struct mg_str (*mg_fu_fname_fn)(struct mg_connection *nc, + struct mg_str fname); +--- + +Callback prototype for `mg_file_upload_handler()`. + diff --git a/docs/c-api/http.h/mg_register_http_endpoint.md b/docs/c-api/http.h/mg_register_http_endpoint.md new file mode 100644 index 00000000..eefbe99e --- /dev/null +++ b/docs/c-api/http.h/mg_register_http_endpoint.md @@ -0,0 +1,35 @@ +--- +title: "mg_register_http_endpoint()" +decl_name: "mg_register_http_endpoint" +symbol_kind: "func" +signature: | + void mg_register_http_endpoint(struct mg_connection *nc, const char *uri_path, + mg_event_handler_t handler); +--- + +Register callback for specified http endpoint +Note: if callback is registered it is called instead of +callback provided in mg_bind + +Example code snippet: + +```c +static void handle_hello1(struct mg_connection *nc, int ev, void *ev_data) { + (void) ev; (void) ev_data; + mg_printf(nc, "HTTP/1.0 200 OK\r\n\r\n[I am Hello1]"); + nc->flags |= MG_F_SEND_AND_CLOSE; +} + +static void handle_hello1(struct mg_connection *nc, int ev, void *ev_data) { + (void) ev; (void) ev_data; + mg_printf(nc, "HTTP/1.0 200 OK\r\n\r\n[I am Hello2]"); + nc->flags |= MG_F_SEND_AND_CLOSE; +} + +void init() { + nc = mg_bind(&mgr, local_addr, cb1); + mg_register_http_endpoint(nc, "/hello1", handle_hello1); + mg_register_http_endpoint(nc, "/hello1/hello2", handle_hello2); +} +``` + diff --git a/mongoose.h b/mongoose.h index ddb91987..810c61e8 100644 --- a/mongoose.h +++ b/mongoose.h @@ -2208,7 +2208,6 @@ void mg_send_websocket_handshake2(struct mg_connection *nc, const char *path, * "clubby.cesanta.com", NULL); * ``` */ - struct mg_connection *mg_connect_ws(struct mg_mgr *mgr, mg_event_handler_t event_handler, const char *url, const char *protocol, @@ -2220,7 +2219,6 @@ struct mg_connection *mg_connect_ws(struct mg_mgr *mgr, * Mostly identical to mg_connect_ws, but allows to provide extra parameters * (for example, SSL parameters */ - struct mg_connection *mg_connect_ws_opt(struct mg_mgr *mgr, mg_event_handler_t ev_handler, struct mg_connect_opts opts, @@ -2456,6 +2454,7 @@ int mg_http_create_digest_auth_header(char *buf, size_t buf_len, const char *method, const char *uri, const char *auth_domain, const char *user, const char *passwd); + /* * Helper function that creates outbound HTTP connection. * @@ -2480,7 +2479,6 @@ int mg_http_create_digest_auth_header(char *buf, size_t buf_len, * "var_1=value_1&var_2=value_2"); * ``` */ - struct mg_connection *mg_connect_http(struct mg_mgr *mgr, mg_event_handler_t event_handler, const char *url, @@ -2493,7 +2491,6 @@ struct mg_connection *mg_connect_http(struct mg_mgr *mgr, * Mostly identical to mg_connect_http, but allows to provide extra parameters * (for example, SSL parameters */ - struct mg_connection *mg_connect_http_opt(struct mg_mgr *mgr, mg_event_handler_t ev_handler, struct mg_connect_opts opts, @@ -2649,11 +2646,15 @@ void mg_serve_http(struct mg_connection *nc, struct http_message *hm, * } * ``` */ - void mg_register_http_endpoint(struct mg_connection *nc, const char *uri_path, mg_event_handler_t handler); #ifdef MG_ENABLE_HTTP_STREAMING_MULTIPART + +/* Callback prototype for `mg_file_upload_handler()`. */ +typedef struct mg_str (*mg_fu_fname_fn)(struct mg_connection *nc, + struct mg_str fname); + /* * File upload handler. * This handler can be used to implement file uploads with minimum code. @@ -2685,9 +2686,6 @@ void mg_register_http_endpoint(struct mg_connection *nc, const char *uri_path, * } * ``` */ - -typedef struct mg_str (*mg_fu_fname_fn)(struct mg_connection *nc, - struct mg_str fname); void mg_file_upload_handler(struct mg_connection *nc, int ev, void *ev_data, mg_fu_fname_fn local_name_fn); #endif /* MG_ENABLE_HTTP_STREAMING_MULTIPART */