1# Ulfius HTTP Framework 2 3 4 5[](https://bestpractices.coreinfrastructure.org/projects/3195) 6 7HTTP Framework for REST Applications in C. 8 9Based on [GNU Libmicrohttpd](https://www.gnu.org/software/libmicrohttpd/) for the backend web server, [Jansson](http://www.digip.org/jansson/) for the json manipulation library, and [Libcurl](http://curl.haxx.se/libcurl/) for the http/smtp client API. 10 11Used to facilitate creation of web applications in C programs with a small memory footprint, as in embedded systems applications. 12 13You can create webservices in HTTP or HTTPS mode, stream data, or implement server websockets. 14 15## Hello World! example application 16 17The source code of a hello world using Ulfius is the following: 18 19```C 20/** 21 * test.c 22 * Small Hello World! example 23 * to compile with gcc, run the following command 24 * gcc -o test test.c -lulfius 25 */ 26#include <stdio.h> 27#include <ulfius.h> 28 29#define PORT 8080 30 31/** 32 * Callback function for the web application on /helloworld url call 33 */ 34int callback_hello_world (const struct _u_request * request, struct _u_response * response, void * user_data) { 35 ulfius_set_string_body_response(response, 200, "Hello World!"); 36 return U_CALLBACK_CONTINUE; 37} 38 39/** 40 * main function 41 */ 42int main(void) { 43 struct _u_instance instance; 44 45 // Initialize instance with the port number 46 if (ulfius_init_instance(&instance, PORT, NULL, NULL) != U_OK) { 47 fprintf(stderr, "Error ulfius_init_instance, abort\n"); 48 return(1); 49 } 50 51 // Endpoint list declaration 52 ulfius_add_endpoint_by_val(&instance, "GET", "/helloworld", NULL, 0, &callback_hello_world, NULL); 53 54 // Start the framework 55 if (ulfius_start_framework(&instance) == U_OK) { 56 printf("Start framework on port %d\n", instance.port); 57 58 // Wait for the user to press <enter> on the console to quit the application 59 getchar(); 60 } else { 61 fprintf(stderr, "Error starting framework\n"); 62 } 63 printf("End framework\n"); 64 65 ulfius_stop_framework(&instance); 66 ulfius_clean_instance(&instance); 67 68 return 0; 69} 70``` 71 72## Main features 73 74### Webservice 75 76- Create a webservice in a separate thread, the endpoint is identified by its method (ex: `GET`, `POST`, `PUT`, `DELETE`, etc.) and its URL path with its optional parameters (ex: `/api/doc/@id`). The webservice is executed in a callback function. 77 78- Stream large amount of data with a reduced memory footprint. 79 80- Websocket service, the websocket messages exchange is executed in dedicated callback functions. 81 82### Client requests 83 84- Client http[s] and smtp requests execution, the response is parsed in a dedicated structure. 85 86- Client websocket request execution, the websocket messages exchange is executed in dedicated callback functions. 87 88### Websockets 89 90- Create a websocket service application 91 92- Create websocket client application 93 94- CLI to connect to a remote websocket: [uwsc](https://github.com/babelouest/ulfius/tree/master/tools/uwsc) 95 96## Installation 97 98See [INSTALL.md](INSTALL.md) file for installation details 99 100## Documentation 101 102See [API.md](API.md) file for API documentation details 103 104See the [online documentation](https://babelouest.github.io/ulfius/) for a doxygen format of the API documentation. 105 106## Example programs source code 107 108Example programs are available to understand the different functionalities available, see [example_programs](https://github.com/babelouest/ulfius/blob/master/example_programs) folder for detailed sample source codes and documentation. 109 110## Example callback functions 111 112Example callback functions are available in the folder [example_callbacks](https://github.com/babelouest/ulfius/blob/master/example_callbacks). The example callback functions available are: 113- static file server: to provide static files of a specific folder 114- oauth2 bearer: to check the validity of a Oauth2 bearer jwt token. Requires [libjwt](https://github.com/benmcollins/libjwt). 115 116## Projects using Ulfius framework 117 118- [Glewlwyd](https://github.com/babelouest/glewlwyd), a lightweight SSO server that provides OAuth2 and OpenID Connect authentication protocols 119- [Le Biniou](https://biniou.net/), user-friendly yet powerful music visualization / VJing tool 120- [Angharad](https://github.com/babelouest/angharad), House automation system for ZWave and other types of devices 121- [Hutch](https://github.com/babelouest/hutch), a safe locker for passwords and other secrets, using JavaScript client side encryption only 122- [Taliesin](https://github.com/babelouest/taliesin), a lightweight audio streaming server 123- [Taulas Raspberry Pi Serial interface](https://github.com/babelouest/taulas/tree/master/taulas_raspberrypi_serial), an interface for Arduino devices that implement [Taulas](https://github.com/babelouest/taulas/) protocol, a house automation protocol for Angharad 124 125## Questions, problems ? 126 127I'm open for questions and suggestions, feel free to open an [issue](https://github.com/babelouest/ulfius/issues), a [pull request](https://github.com/babelouest/ulfius/pulls) or send me an [e-mail](mailto:mail@babelouest.org) if you feel like it! 128 129You can visit the IRC channel #ulfius on the [Freenode](https://freenode.net/) network. 130
){kind=link}
){kind=link}