mirror/mongoose
1
0
Fork 0
mirror of https://github.com/cesanta/mongoose.git synced 2024-11-29 14:49:00 +08:00
Code Issues Actions 5 Packages Projects Releases Wiki Activity

API.md is split to API.md and Embed.md

Browse Source
This commit is contained in:
Sergey Lyubka 2013-12-10 11:16:25 +00:00
parent d4eae0e251
commit 9bd5903f1d
2 changed files with 88 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
docs/API.md
View File

@ -1,63 +1,4 @@
# Mongoose Embedding Guide
Embedding Mongoose is done in two steps:
1. Copy
[mongoose.c](https://raw.github.com/cesanta/mongoose/master/mongoose.c) and
[mongoose.h](https://raw.github.com/cesanta/mongoose/master/mongoose.h)
to your application's source tree and include these two files in the build.
2. Somewhere in the application code, call `mg_create_server()` to create
a server, configure it with `mg_set_option()` and loop with
`mg_poll_server()` until done. Call `mg_destroy_server()` to cleanup.
Here's minimal application, suppose it is in the `minimal.c` file:
#include "mongoose.h"
int main(void) {
struct mg_server *server = mg_create_server(NULL);
mg_set_option(server, "document_root", ".");
mg_set_option(server, "listening_port", "8080");
for (;;) mg_poll_server(server, 1000); // Infinite loop, Ctrl-C to stop
mg_destroy_server(&server);
return 0;
}
To compile it, put `mongoose.c`, `mongoose.h` and `minimal.c` into one
folder, then run the following UNIX command:
cc minimal.c mongoose.c -o my_program
If you're on Windows, run this in a Visual Studio shell:
cl minimal.c mongoose.c /TC /MD
Mongoose can call user-defined functions when certain URIs are requested.
These functions are _called uri handlers_. `mg_add_uri_handler()` registers
an URI handler, and there is no restriction on the number of URI handlers.
Also, mongoose can call a user-defined function when it is about to send
HTTP error back to client. HTTP error handler function can be registered
with `mg_set_http_error_handler()`.
In a handler function, user code
can get all information about the request -- parsed headers, etcetera.
Here is a list of well-commented embedding examples:
* [hello.c](https://github.com/cesanta/mongoose/blob/master/examples/hello.c)
This is the most basic "Hello, world!" example
* [post.c](https://github.com/cesanta/mongoose/blob/master/examples/post.c)
This example shows how to handle form submission
* [upload.c](https://github.com/cesanta/mongoose/blob/master/examples/upload.c)
This example shows how to handle file upload
* [websocket.c](https://github.com/cesanta/mongoose/blob/master/examples/websocket.c)
This example shows how to handle websocket requests
* [chat.c](https://github.com/cesanta/mongoose/blob/master/examples/chat.c), [main.js](https://github.com/cesanta/mongoose/blob/master/examples/html/main.js)
An example of web chat application, with cookie-based user authentication,
session support. All UI is done using static HTML/CSS. Interaction
with backed is done using AJAX.
# API Reference
# Mongoose API Reference
struct mg_context *mg_start(const char **configuration_options
int (*event_handler_func)(struct mg_event *),

87
docs/Embed.md Normal file
View File

@ -0,0 +1,87 @@
# Mongoose Embedding Guide
Embedding Mongoose is done in two steps:
1. Copy
[mongoose.c](https://raw.github.com/cesanta/mongoose/master/mongoose.c) and
[mongoose.h](https://raw.github.com/cesanta/mongoose/master/mongoose.h)
to your application's source tree and include these two files in the build.
2. Somewhere in the application code, call `mg_create_server()` to create
a server, configure it with `mg_set_option()` and loop with
`mg_poll_server()` until done. Call `mg_destroy_server()` to cleanup.
Here's a minimal application `app.c` that embeds mongoose:
#include "mongoose.h"
int main(void) {
struct mg_server *server = mg_create_server(NULL);
mg_set_option(server, "document_root", ".");
mg_set_option(server, "listening_port", "8080");
for (;;) mg_poll_server(server, 1000); // Infinite loop, Ctrl-C to stop
mg_destroy_server(&server);
return 0;
}
To compile it, put `mongoose.c`, `mongoose.h` and `minimal.c` into one
folder, then run the following UNIX command:
cc app.c mongoose.c -o app
If you're on Windows, run this in a Visual Studio shell:
cl app.c mongoose.c /TC /MD
When run, this simple application opens port 8080 and serves static files,
CGI files and lists directory content in the current working directory.
Mongoose can call user-defined functions when certain URIs are requested.
These functions are _called uri handlers_. `mg_add_uri_handler()` registers
an URI handler, and there is no restriction exist on the number of URI handlers.
Also, mongoose can call a user-defined function when it is about to send
HTTP error back to client. That function is called _http error handler_ and
can be registered by `mg_set_http_error_handler()`. Handlers are called
by Mongoose with `struct mg_connection *` pointer as a parameter, which
has all information about the request: HTTP headers, POST or websocket
data buffer, etcetera.
Let's extend our minimal application example and
create an URI that will be served by user's C code. The app will handle
`/hello` URI by showing a hello message. So, when app is run,
http://127.0.0.1:8080/hello will say hello, and here's the code:
#include <string.h>
#include "mongoose.h"
static int handle_hello(struct mg_connection *conn) {
static const char *reply = "HTTP/1.0 200 OK\r\n\r\nHello world!\n";
mg_write(conn, reply, strlen(reply));
return 1;
}
int main(void) {
struct mg_server *server = mg_create_server(NULL);
mg_set_option(server, "document_root", ".");
mg_set_option(server, "listening_port", "8080");
mg_add_uri_handler(server, "/hello", &handle_hello);
for (;;) mg_poll_server(server, 1000); // Infinite loop, Ctrl-C to stop
mg_destroy_server(&server);
return 0;
}
Note that URI handler must output valid HTTP response, which includes
the reply line with status code `HTTP/1.0 200 OK`, HTTP headers which are
empty in our example, and message body `Hello world!\n`. Note that reply
line is ended with `\r\n`, and HTTP headers are also ended with `\r\n`.
Mongoose source code contains a well-commented example code, listed below:
* [hello.c](https://github.com/cesanta/mongoose/blob/master/examples/hello.c)
shows how to handle form input, file upload, websocket communication, get
cookie values.
* [chat](https://github.com/cesanta/mongoose/blob/master/examples/chat)
implements basic online chat functionality using Lua scripting capabilities
of Mongoose. Not a single line of C is written for that example.
Demostrates usage of database, cookie-based authentication, session
support, RESTful interface. No additional software is required to run it
on any platform.