Ulfius: Ulfius HTTP Framework

Ulfius HTTP Framework for REST Applications in C

Loading...
Searching...
No Matches
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:1559
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:1745
ulfius_clean_instance
void ulfius_clean_instance(struct _u_instance *u_instance)
Definition: ulfius.c:1638
ulfius_stop_framework
int ulfius_stop_framework(struct _u_instance *u_instance)
Definition: ulfius.c:1315
ulfius_start_framework
int ulfius_start_framework(struct _u_instance *u_instance)
Definition: ulfius.c:1162
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:507
_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.