Ulfius: Ulfius HTTP Framework

Ulfius HTTP Framework for REST Applications in C

Ulfius HTTP Framework

HTTP Framework for REST Applications in C.

Based on GNU Libmicrohttpd for the backend web server, Jansson for the json manipulation library, and Libcurl for the http/smtp client API.

Used to facilitate creation of web applications in C programs with a small memory footprint, as in embedded systems applications.

You can create webservices in HTTP or HTTPS mode, stream data, or implement server websockets.

# Hello World! example application

The source code of a hello world using Ulfius is the following:

#include <stdio.h>
#include <ulfius.h>
#define PORT 8080
int callback_hello_world (const struct _u_request * request, struct _u_response * response, void * user_data) {
ulfius_set_string_body_response(response, 200, "Hello World!");
return U_CALLBACK_CONTINUE;
}
int main(void) {
struct _u_instance instance;
// Initialize instance with the port number
if (ulfius_init_instance(&instance, PORT, NULL, NULL) != U_OK) {
fprintf(stderr, "Error ulfius_init_instance, abort\n");
return(1);
}
// Endpoint list declaration
ulfius_add_endpoint_by_val(&instance, "GET", "/helloworld", NULL, 0, &callback_hello_world, NULL);
// Start the framework
if (ulfius_start_framework(&instance) == U_OK) {
printf("Start framework on port %d\n", instance.port);
// Wait for the user to press <enter> on the console to quit the application
getchar();
} else {
fprintf(stderr, "Error starting framework\n");
}
printf("End framework\n");
ulfius_stop_framework(&instance);
ulfius_clean_instance(&instance);
return 0;
}
U_OK
#define U_OK
No error.
Definition ulfius.h:110
U_CALLBACK_CONTINUE
#define U_CALLBACK_CONTINUE
Callback exited with success, continue to next callback.
Definition ulfius.h:119
ulfius_add_endpoint_by_val
int ulfius_add_endpoint_by_val(struct _u_instance *u_instance, const char *http_method, const char *url_prefix, const char *url_format, unsigned int priority, int(*callback_function)(const struct _u_request *request, struct _u_response *response, void *user_data), void *user_data)
Definition ulfius.c:1545
ulfius_init_instance
int ulfius_init_instance(struct _u_instance *u_instance, unsigned int port, struct sockaddr_in *bind_address, const char *default_auth_realm)
Definition ulfius.c:1732
ulfius_clean_instance
void ulfius_clean_instance(struct _u_instance *u_instance)
Definition ulfius.c:1624
ulfius_stop_framework
int ulfius_stop_framework(struct _u_instance *u_instance)
Definition ulfius.c:1301
ulfius_start_framework
int ulfius_start_framework(struct _u_instance *u_instance)
Definition ulfius.c:1166
ulfius_set_string_body_response
int ulfius_set_string_body_response(struct _u_response *response, const unsigned int status, const char *string_body)
Definition u_response.c:516
_u_instance
Contains the needed data for an ulfius instance to work.
Definition ulfius.h:316
_u_request
definition of the parameters available in a struct _u_request
Definition ulfius.h:233
_u_response
definition of the parameters available in a struct _u_response
Definition ulfius.h:273
ulfius.h
Ulfius framework.

# Main features

## Webservice

- 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.
- Stream large amount of data with a reduced memory footprint.
- Websocket service, the websocket messages exchange is executed in dedicated callback functions.

## Client requests

- Client http[s] and smtp requests execution, the response is parsed in a dedicated structure.
- Client websocket request execution, the websocket messages exchange is executed in dedicated callback functions.

## Websockets

- Create a websocket service application
- Create websocket client application
- CLI to connect to a remote websocket: uwsc

# Installation

See INSTALL.md file for installation details

# Documentation

See API.md file for API documentation details

See the online documentation for a doxygen format of the API documentation.

# Example programs source code

Example programs are available to understand the different functionalities available, see example_programs folder for detailed sample source codes and documentation.

# Example callback functions

Example callback functions are available in the folder example_callbacks. The example callback functions available are:

- static file server: to provide static files of a specific folder
- oauth2 bearer: to check the validity of a Oauth2 bearer jwt token. Requires libjwt.

# Projects using Ulfius framework

- Glewlwyd, a lightweight SSO server that provides OAuth2 and OpenID Connect authentication protocols
- Le Biniou, user-friendly yet powerful music visualization / VJing tool
- Angharad, House automation system for ZWave and other types of devices
- Hutch, a safe locker for passwords and other secrets, using JavaScript client side encryption only
- Taliesin, a lightweight audio streaming server
- Taulas Raspberry Pi Serial interface, an interface for Arduino devices that implement Taulas protocol, a house automation protocol for Angharad

# Questions, problems ?

I'm open for questions and suggestions, feel free to open an issue, a pull request or send me an e-mail if you feel like it!

You can visit the IRC channel #ulfius on the Libera.​Chat network.