Skip to content
Snippets Groups Projects
Commit 3eb4eb80 authored by Dmitry Frank's avatar Dmitry Frank
Browse files

Fix mongoose docs generation

PUBLISHED_FROM=331821dcd1f7dc8a94581cd8a9b51aa00a89fddc
parent ab000c68
No related branches found
No related tags found
No related merge requests found
Showing
with 408 additions and 0 deletions
---
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
MG_UD_ARG(void *user_data);
---
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. A 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;
}
}
```
---
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()`.
---
title: "mg_get_http_basic_auth()"
decl_name: "mg_get_http_basic_auth"
symbol_kind: "func"
signature: |
int mg_get_http_basic_auth(struct http_message *hm, char *user, size_t user_len,
char *pass, size_t pass_len);
---
Gets and parses the Authorization: Basic header
Returns -1 if no Authorization header is found, or if
mg_parse_http_basic_auth
fails parsing the resulting header.
---
title: "mg_get_http_header()"
decl_name: "mg_get_http_header"
symbol_kind: "func"
signature: |
struct mg_str *mg_get_http_header(struct http_message *hm, const char *name);
---
Searches and returns the header `name` in parsed HTTP message `hm`.
If header is not found, NULL is returned. Example:
struct mg_str *host_hdr = mg_get_http_header(hm, "Host");
---
title: "mg_get_http_var()"
decl_name: "mg_get_http_var"
symbol_kind: "func"
signature: |
int mg_get_http_var(const struct mg_str *buf, const char *name, char *dst,
size_t dst_len);
---
Fetches a HTTP form variable.
Fetches a variable `name` from a `buf` into a buffer specified by `dst`,
`dst_len`. The destination is always zero-terminated. Returns the length of
a fetched variable. If not found, 0 is returned. `buf` must be valid
url-encoded buffer. If destination is too small or an error occured,
negative number is returned.
---
title: "mg_http_check_digest_auth()"
decl_name: "mg_http_check_digest_auth"
symbol_kind: "func"
signature: |
int mg_http_check_digest_auth(struct http_message *hm, const char *auth_domain,
FILE *fp);
---
Authenticates a HTTP request against an opened password file.
Returns 1 if authenticated, 0 otherwise.
---
title: "mg_http_parse_header()"
decl_name: "mg_http_parse_header"
symbol_kind: "func"
signature: |
int mg_http_parse_header(struct mg_str *hdr, const char *var_name, char *buf,
size_t buf_size);
---
Parses the HTTP header `hdr`. Finds variable `var_name` and stores its value
in the buffer `buf`, `buf_size`. Returns 0 if variable not found, non-zero
otherwise.
This function is supposed to parse cookies, authentication headers, etc.
Example (error handling omitted):
char user[20];
struct mg_str *hdr = mg_get_http_header(hm, "Authorization");
mg_http_parse_header(hdr, "username", user, sizeof(user));
Returns the length of the variable's value. If buffer is not large enough,
or variable not found, 0 is returned.
---
title: "mg_http_reverse_proxy()"
decl_name: "mg_http_reverse_proxy"
symbol_kind: "func"
signature: |
void mg_http_reverse_proxy(struct mg_connection *nc,
const struct http_message *hm, struct mg_str mount,
struct mg_str upstream);
---
Proxies a given request to a given upstream http server. The path prefix
in `mount` will be stripped of the path requested to the upstream server,
e.g. if mount is /api and upstream is http://localhost:8001/foo
then an incoming request to /api/bar will cause a request to
http://localhost:8001/foo/bar
EXPERIMENTAL API. Please use http_serve_http + url_rewrites if a static
mapping is good enough.
---
title: "mg_http_send_error()"
decl_name: "mg_http_send_error"
symbol_kind: "func"
signature: |
void mg_http_send_error(struct mg_connection *nc, int code, const char *reason);
---
Sends an error response. If reason is NULL, the message will be inferred
from the error code (if supported).
---
title: "mg_http_send_redirect()"
decl_name: "mg_http_send_redirect"
symbol_kind: "func"
signature: |
void mg_http_send_redirect(struct mg_connection *nc, int status_code,
const struct mg_str location,
const struct mg_str extra_headers);
---
Sends a redirect response.
`status_code` should be either 301 or 302 and `location` point to the
new location.
If `extra_headers` is not empty, then `extra_headers` are also sent
after the response line. `extra_headers` must NOT end end with new line.
Example:
mg_http_send_redirect(nc, 302, mg_mk_str("/login"), mg_mk_str(NULL));
---
title: "mg_http_serve_file()"
decl_name: "mg_http_serve_file"
symbol_kind: "func"
signature: |
void mg_http_serve_file(struct mg_connection *nc, struct http_message *hm,
const char *path, const struct mg_str mime_type,
const struct mg_str extra_headers);
---
Serves a specific file with a given MIME type and optional extra headers.
Example code snippet:
```c
static void ev_handler(struct mg_connection *nc, int ev, void *ev_data) {
switch (ev) {
case MG_EV_HTTP_REQUEST: {
struct http_message *hm = (struct http_message *) ev_data;
mg_http_serve_file(nc, hm, "file.txt",
mg_mk_str("text/plain"), mg_mk_str(""));
break;
}
...
}
}
```
---
title: "mg_parse_http()"
decl_name: "mg_parse_http"
symbol_kind: "func"
signature: |
int mg_parse_http(const char *s, int n, struct http_message *hm, int is_req);
---
Parses a HTTP message.
`is_req` should be set to 1 if parsing a request, 0 if reply.
Returns the number of bytes parsed. If HTTP message is
incomplete `0` is returned. On parse error, a negative number is returned.
---
title: "mg_parse_http_basic_auth()"
decl_name: "mg_parse_http_basic_auth"
symbol_kind: "func"
signature: |
int mg_parse_http_basic_auth(struct mg_str *hdr, char *user, size_t user_len,
char *pass, size_t pass_len);
---
Parses the Authorization: Basic header
Returns -1 iif the authorization type is not "Basic" or any other error such
as incorrectly encoded base64 user password pair.
---
title: "mg_parse_multipart()"
decl_name: "mg_parse_multipart"
symbol_kind: "func"
signature: |
size_t mg_parse_multipart(const char *buf, size_t buf_len, char *var_name,
size_t var_name_len, char *file_name,
size_t file_name_len, const char **chunk,
size_t *chunk_len);
---
Parses the buffer `buf`, `buf_len` that contains multipart form data chunks.
Stores the chunk name in a `var_name`, `var_name_len` buffer.
If a chunk is an uploaded file, then `file_name`, `file_name_len` is
filled with an uploaded file name. `chunk`, `chunk_len`
points to the chunk data.
Return: number of bytes to skip to the next chunk or 0 if there are
no more chunks.
Usage example:
```c
static void ev_handler(struct mg_connection *nc, int ev, void *ev_data) {
switch(ev) {
case MG_EV_HTTP_REQUEST: {
struct http_message *hm = (struct http_message *) ev_data;
char var_name[100], file_name[100];
const char *chunk;
size_t chunk_len, n1, n2;
n1 = n2 = 0;
while ((n2 = mg_parse_multipart(hm->body.p + n1,
hm->body.len - n1,
var_name, sizeof(var_name),
file_name, sizeof(file_name),
&chunk, &chunk_len)) > 0) {
printf("var: %s, file_name: %s, size: %d, chunk: [%.*s]\n",
var_name, file_name, (int) chunk_len,
(int) chunk_len, chunk);
n1 += n2;
}
}
break;
```
---
title: "mg_printf_html_escape()"
decl_name: "mg_printf_html_escape"
symbol_kind: "func"
signature: |
void mg_printf_html_escape(struct mg_connection *nc, const char *fmt, ...);
---
Sends a printf-formatted HTTP chunk, escaping HTML tags.
---
title: "mg_printf_http_chunk()"
decl_name: "mg_printf_http_chunk"
symbol_kind: "func"
signature: |
void mg_printf_http_chunk(struct mg_connection *nc, const char *fmt, ...);
---
Sends a printf-formatted HTTP chunk.
Functionality is similar to `mg_send_http_chunk()`.
---
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_CB(mg_event_handler_t handler,
void *user_data);
---
Registers a callback for a specified http endpoint
Note: if callback is registered it is called instead of the
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_hello2(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);
}
```
---
title: "mg_send_head()"
decl_name: "mg_send_head"
symbol_kind: "func"
signature: |
void mg_send_head(struct mg_connection *n, int status_code,
int64_t content_length, const char *extra_headers);
---
Sends the response line and headers.
This function sends the response line with the `status_code`, and
automatically
sends one header: either "Content-Length" or "Transfer-Encoding".
If `content_length` is negative, then "Transfer-Encoding: chunked" header
is sent, otherwise, "Content-Length" header is sent.
NOTE: If `Transfer-Encoding` is `chunked`, then message body must be sent
using `mg_send_http_chunk()` or `mg_printf_http_chunk()` functions.
Otherwise, `mg_send()` or `mg_printf()` must be used.
Extra headers could be set through `extra_headers`. Note `extra_headers`
must NOT be terminated by a new line.
---
title: "mg_send_http_chunk()"
decl_name: "mg_send_http_chunk"
symbol_kind: "func"
signature: |
void mg_send_http_chunk(struct mg_connection *nc, const char *buf, size_t len);
---
Sends buffer `buf` of size `len` to the client using chunked HTTP encoding.
This function sends the buffer size as hex number + newline first, then
the buffer itself, then the newline. For example,
`mg_send_http_chunk(nc, "foo", 3)` will append the `3\r\nfoo\r\n` string
to the `nc->send_mbuf` output IO buffer.
NOTE: The HTTP header "Transfer-Encoding: chunked" should be sent prior to
using this function.
NOTE: do not forget to send an empty chunk at the end of the response,
to tell the client that everything was sent. Example:
```
mg_printf_http_chunk(nc, "%s", "my response!");
mg_send_http_chunk(nc, "", 0); // Tell the client we're finished
```
---
title: "mg_send_response_line()"
decl_name: "mg_send_response_line"
symbol_kind: "func"
signature: |
void mg_send_response_line(struct mg_connection *nc, int status_code,
const char *extra_headers);
---
Sends the response status line.
If `extra_headers` is not NULL, then `extra_headers` are also sent
after the response line. `extra_headers` must NOT end end with new line.
Example:
mg_send_response_line(nc, 200, "Access-Control-Allow-Origin: *");
Will result in:
HTTP/1.1 200 OK\r\n
Access-Control-Allow-Origin: *\r\n
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment