低资源系统中处理HTTP请求的微型C库：ureq
ureq是低资源系统中处理HTTP请求的微型C库。
How does it work?
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, UREQ_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.
Basic usage
As said before,ureqis used for dispatching. Let's add a couple of urls then:
ureq_serve("/", s_home, UREQ_GET); ureq_serve("/post", s_post, UREQ_POST); ... ureq_serve("/all", s_all, UREQ_ALL); How does it work? When there's a request for an url (/,/all,/post), with corresponding method (UREQ_GET,UREQ_POST,UREQ_PUT,UREQ_DELETE,UREQ_ALL), ureq calls the corresponding function (s_home(),s_post(), ...,s_all()). What'sUREQ_ALLmethod? 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 toHttpRequest:
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);
requestin 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(r.response.data, r.len);
and do all the sending job inside it (sendis our sending function in that case, remember to replace it with one used by your server backend,r.response.datais the response generated by ureq, andreq.lenis its length.
If you wish, do something else withHttpRequestnow. When you're ready, call
ureq_close(&r);
To perform a cleanup. Seeexamples/example.cfor basic server-less request parser. Seeexamples/example-server.cfor basic unix http server.
That's all.
Let's summarize:
#include "ureq.h" char *s_home() { return "home"; } int main() { ureq_serve("/", s_home, UREQ_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; }Detailed usage
This part ofREADMEneeds 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 framework viaureq_serve. Readingureq.hfile may provide many useful informations.
Let's take a look atResponsestruct, which is initialized in every request struct:
typedef struct ureq_response_t { int code; char *mime; char *header; char *data; char *file; } UreqResponse; Except*data, these parameters can be set from your page functions. Some examples:
Set response code
r->response.code = 302;
Set custom response header
r->response.header = "Location: /";
Set response mime-type:
r->reponse.mime = "text/plain";
Load test
With the help of Reddit and Hacker News users,ureqwas benchmarked on theESP8266.
For more data, go to: http://ureq.solusipse.net.
Roadmap
- minimal templating system
- file sending on unix systems
- todos from comments in files