Micro C library for handling HTTP requests on low resource systems. Please note that ureq is still in heavy development and new features are continuously added. Despite this, it behaves very well in stability tests and current user-end interface won't be probably changed.
ureq is a middleware that sits between any kind of tcp server and the core of your application. Use it to dispatch urls to functions, like this: ureq_serve("/", my_function, GET);
. It supports basic http functionality and can be used anywhere system resources are low (it was built for embedded systems, e.g. ESP8266) or where sophisticated http features aren't needed. And yes, it understands RESTful.
As said before, ureq
is used for dispatching. Let's add a couple of urls then:
ureq_serve("/", s_home, GET);
ureq_serve("/post", s_post, POST);
...
ureq_serve("/all", s_all, ALL);
How does it work? When there's a request for an url (/
, /all
, /post
), with corresponding method (GET
, POST
, PUT
, DELETE
, ALL
), ureq calls the corresponding function (s_home()
, s_post()
, ..., s_all()
). What's ALL
method? It calls a function connected to the url, no matter which type of method was used.
But wait, how should such function look like? The only requirement is that it has to return a string that will be sent to a client. For example:
char *some_function() {
return "<h1>Some text!</h1>";
}
You want to parse GET parameters or do something with POST data? No problem, just define your function with a pointer to HttpRequest
:
char *fancy_function(HttpRequest *r) {
// Do something here, see detailed usage and examples for more info
return "<h1>Some text!</h1>";
}
Keep in mind that adding struct argument to the function's definition is not obligatory.
We connected some urls to functions, what's next?
We have to create a structure that holds all the data and initialize it. And we have to do it per every request. Simply put such line in your program:
HttpRequest r = ureq_init(request);
request
in that case is everything you got from the client.
Now let the magic happen. Put such loop in your code:
while(ureq_run(&r)) send(req.response.data, req.len);
and do all the sending job inside it (send
is our sending function in that case, remember to replace it with one used by your server backend, req.response.data
is the response generated by ureq, and req.len
is its length.
If you wish, do something else with HttpRequest
now. When you're ready, call
ureq_close(&req);
To perform a cleanup. See examples/example.c
for basic server-less request parser. See examples/example-server.c
for basic unix http server.
That's all.
Let's summarize:
#include "ureq.c"
char *s_home() {
return "home";
}
int main() {
ureq_serve("/", s_home, GET);
char request[] = "GET / HTTP/1.1\n"
"Host: 127.0.0.1:80\n";
HttpRequest r = ureq_init(request);
while(ureq_run(&r)) printf("%s\n", r.response.data);
ureq_close(&r);
ureq_finish();
return 0;
}
This part of README
needs to be improved, please treat it as an early draft.
To take precise control of server's response, modify HttpRequest struct's fields inside page connected to framwork via ureq_serve
. Reading ureq.h
file may provide many useful informations.
Let's take a look at Response
struct, which is initialized in every request struct:
struct Response {
int code;
char *mime;
char *header;
char *data;
};
Except *data
, these parameters can be set from your page functions. Some examples:
r->response.code = 302;
r->response.header = "Location: /";
r->reponse.mime = "text/plain";
- minimal templating system
- file sending on unix systems
- todos from comments in files
See LICENSE
.