### Hello World Example Application

Source: https://babelouest.github.io/ulfius/md_README.html

A basic 'Hello World' example demonstrating how to initialize Ulfius, add a simple GET endpoint, and start the framework. Ensure Ulfius is correctly installed and linked.

```c
#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;
}
```

--------------------------------

### Install uwsc command-line tool

Source: https://babelouest.github.io/ulfius/md_INSTALL.html

Navigate to the `uwsc/` directory and use `make` followed by `sudo make install` to compile and install the `uwsc` tool. The installation directory can be changed using `DESTDIR`.

```bash
cd ulfius/uwsc
$ make && sudo make install
```

--------------------------------

### Start Ulfius Framework

Source: https://babelouest.github.io/ulfius/ulfius_8c.html

Initializes and starts the Ulfius HTTP framework. Ensure the instance is properly initialized before calling this function.

```c
int ulfius_start_framework(struct _u_instance *u_instance)
```

--------------------------------

### Compile and Install Orcania using Makefile

Source: https://babelouest.github.io/ulfius/md_INSTALL.html

Compiles and installs the Orcania library from source using its Makefile. Ensure previous versions are removed before proceeding.

```bash
cd <orcania_source>
make && sudo make install
```

--------------------------------

### Start Webservice

Source: https://babelouest.github.io/ulfius/index.html

Functions to start the UlfiUS web framework with different security configurations.

```APIDOC
## Start webservice 
The starting point function are `ulfius_start_framework`, `ulfius_start_secure_framework`, `ulfius_start_secure_ca_trust_framework` or `ulfius_start_framework_with_mhd_options`:
```c
int ulfius_start_framework(struct _u_instance * u_instance);
int ulfius_start_secure_framework(struct _u_instance * u_instance, const char * key_pem, const char * cert_pem);
int ulfius_start_secure_ca_trust_framework(struct _u_instance * u_instance, const char * key_pem, const char * cert_pem, const char * root_ca_pem);
int ulfius_start_framework_with_mhd_options(struct _u_instance * u_instance, unsigned int mhd_flags, struct MHD_OptionItem * options);
```
`ulfius_start_framework_with_mhd_options`
```c
int ulfius_start_framework_with_mhd_options(struct _u_instance *u_instance, unsigned int mhd_flags, struct MHD_OptionItem *mhd_ops)
**Definition:** ulfius.c:1274
```
`ulfius_start_secure_ca_trust_framework`
```c
int ulfius_start_secure_ca_trust_framework(struct _u_instance *u_instance, const char *key_pem, const char *cert_pem, const char *root_ca_pem)
**Definition:** ulfius.c:1232
```
`ulfius_start_framework`
```c
int ulfius_start_framework(struct _u_instance *u_instance)
**Definition:** ulfius.c:1166
```
`ulfius_start_secure_framework`
```c
int ulfius_start_secure_framework(struct _u_instance *u_instance, const char *key_pem, const char *cert_pem)
**Definition:** ulfius.c:1183
```
In your program, where you want to start the web server, execute the function `ulfius_start_framework(struct _u_instance * u_instance)` for a non-secure http connection. Use the function `ulfius_start_secure_framework(struct _u_instance * u_instance, const char * key_pem, const char * cert_pem)` for a secure https connection, using a valid private key and a valid corresponding server certificate, see GnuTLS documentation for certificate generation. Finally, use the function `int ulfius_start_secure_ca_trust_framework(struct _u_instance * u_instance, const char * key_pem, const char * cert_pem, const char * root_ca_pem)` to start a secure https connection and be able to authenticate clients with a certificate. Those function accept the previously declared `instance` as first parameter. You can reuse the same callback function as much as you want for different endpoints. On success, these functions returns `U_OK`, otherwise an error code. Note: for security concerns, after running `ulfius_start_secure_framework` or `ulfius_start_secure_ca_trust_framework`, you can free the parameters `key_pem`, `cert_pem` and `root_ca_pem` if you want to.
```

--------------------------------

### Framework Initialization and Start

Source: https://babelouest.github.io/ulfius/ulfius_8c.html

Functions to initialize and start the Ulfius framework, with options for secure connections and custom configurations.

```APIDOC
## ulfius_start_framework()

### Description
Starts the Ulfius framework.

### Method
int

### Parameters
- **u_instance** (*struct _u_instance* *) - Pointer to the Ulfius instance.

### Return Value
Returns 0 on success, -1 on error.
```

```APIDOC
## ulfius_start_secure_framework()

### Description
Starts the Ulfius framework with SSL/TLS support.

### Method
int

### Parameters
- **u_instance** (*struct _u_instance* *) - Pointer to the Ulfius instance.
- **key_pem** (*const char* *) - Path to the private key file in PEM format.
- **cert_pem** (*const char* *) - Path to the certificate file in PEM format.

### Return Value
Returns 0 on success, -1 on error.
```

```APIDOC
## ulfius_start_secure_ca_trust_framework()

### Description
Starts the Ulfius framework with SSL/TLS support and CA trust configuration.

### Method
int

### Parameters
- **u_instance** (*struct _u_instance* *) - Pointer to the Ulfius instance.
- **key_pem** (*const char* *) - Path to the private key file in PEM format.
- **cert_pem** (*const char* *) - Path to the certificate file in PEM format.
- **root_ca_pem** (*const char* *) - Path to the root CA certificate file in PEM format.

### Return Value
Returns 0 on success, -1 on error.
```

```APIDOC
## ulfius_start_framework_with_mhd_options()

### Description
Starts the Ulfius framework with custom Microhttpd options.

### Method
int

### Parameters
- **u_instance** (*struct _u_instance* *) - Pointer to the Ulfius instance.
- **mhd_flags** (*unsigned int*) - Flags for Microhttpd options.
- **mhd_ops** (*struct MHD_OptionItem* *) - Array of Microhttpd option items.

### Return Value
Returns 0 on success, -1 on error.
```

--------------------------------

### Compile and Install Ulfius using Makefile

Source: https://babelouest.github.io/ulfius/md_INSTALL.html

Compiles and installs the Ulfius library from source using its Makefile. This is the final step in the manual installation process.

```bash
cd <ulfius_source>
make && sudo make install
```

--------------------------------

### Start Ulfius Framework (Non-Secure)

Source: https://babelouest.github.io/ulfius/index.html

Starts the Ulfius web service for a non-secure HTTP connection. Accepts the instance as the first parameter and returns U_OK on success.

```c
int ulfius_start_framework(struct _u_instance * u_instance);
```

--------------------------------

### Compile and Install Yder using Makefile

Source: https://babelouest.github.io/ulfius/md_INSTALL.html

Compiles and installs the Yder library from source using its Makefile. This should be done after Orcania and before Ulfius.

```bash
cd <yder_source>
make && sudo make install
```

--------------------------------

### WebSocket Start Callback

Source: https://babelouest.github.io/ulfius/u__private_8h_source.html

Callback function invoked when a WebSocket connection starts. Handles initial handshake and connection setup.

```APIDOC
## ulfius_start_websocket_cb

### Description
Callback function invoked when a WebSocket connection starts. Handles initial handshake and connection setup.

### Function Signature
`void ulfius_start_websocket_cb (void *cls,
struct MHD_Connection *connection,
void *con_cls,
const char *extra_in,
size_t extra_in_size,
MHD_socket sock,
struct MHD_UpgradeResponseHandle *urh);`

### Parameters
* **cls** (void *) - User-defined data.
* **connection** (struct MHD_Connection *) - The connection handle.
* **con_cls** (void *) - Connection-specific data.
* **extra_in** (const char *) - Additional data received during the upgrade request.
* **extra_in_size** (size_t) - Size of the additional data.
* **sock** (MHD_socket) - The socket associated with the connection.
* **urh** (struct MHD_UpgradeResponseHandle *) - Handle for the upgrade response.
```

--------------------------------

### Install Ulfius as a static archive

Source: https://babelouest.github.io/ulfius/md_INSTALL.html

Use the `make static` and `make static-install` commands to install Ulfius as a static archive (`libulfius.a`). You can specify a destination directory using `DESTDIR`.

```bash
cd src
$ make static && sudo make static-install # or make DESTDIR=/tmp static-install if you want to install in `/tmp/lib`
```

--------------------------------

### Install Ulfius to a custom directory

Source: https://babelouest.github.io/ulfius/md_INSTALL.html

Modify the `DESTDIR` value in the `Makefile` files to change the default installation location. Use `make DESTDIR=/tmp install` to install in `/tmp/lib` for example.

```bash
$ make DESTDIR=/tmp install # to install ulfius in /tmp/lib for example
```

--------------------------------

### Start Ulfius Secure Framework

Source: https://babelouest.github.io/ulfius/ulfius_8c.html

Starts the Ulfius framework with SSL/TLS support. Requires valid PEM-encoded key and certificate files.

```c
int ulfius_start_secure_framework(struct _u_instance *u_instance, const char *key_pem, const char *cert_pem)
```

--------------------------------

### ulfius_start_framework

Source: https://babelouest.github.io/ulfius/group__instance.html

Initializes the Ulfius framework and starts the web service based on the provided instance configuration. It listens on the configured port and IP address.

```APIDOC
## ulfius_start_framework()

### Description
Initializes the framework and runs the webservice based on the parameters given.

### Parameters
- **u_instance** (*struct _u_instance*): Pointer to a struct _u_instance that describes its port and bind address.

### Returns
- **int**: U_OK on success.
```

--------------------------------

### Start Ulfius Framework with MHD Options

Source: https://babelouest.github.io/ulfius/ulfius_8c.html

Starts the Ulfius framework with custom libmicrohttpd flags and options. Useful for advanced configuration.

```c
int ulfius_start_framework_with_mhd_options(struct _u_instance *u_instance, unsigned int mhd_flags, struct MHD_OptionItem *mhd_ops)
```

--------------------------------

### ulfius_start_framework_with_mhd_options

Source: https://babelouest.github.io/ulfius/group__instance.html

Initializes the Ulfius framework and starts the web service with custom MicroHTTPD options. Allows for advanced configuration of the underlying HTTP server.

```APIDOC
## ulfius_start_framework_with_mhd_options()

### Description
Initializes the framework and runs the webservice based on the parameters given with custom MicroHTTPD options.

### Parameters
- **u_instance** (*struct _u_instance*): Pointer to a struct _u_instance that describes its port and bind address.
- **mhd_flags** (*unsigned int*): Flags to configure MicroHTTPD behavior.
- **mhd_ops** (*struct MHD_OptionItem*): An array of MicroHTTPD options.

### Returns
- **int**: U_OK on success.
```

--------------------------------

### Install External Dependencies for Ulfius on Debian

Source: https://babelouest.github.io/ulfius/md_INSTALL.html

Installs all necessary external development libraries for building Ulfius on Debian Stretch. This is a prerequisite for manual installation.

```bash
apt install -y libmicrohttpd-dev libjansson-dev libcurl4-gnutls-dev libgnutls28-dev libgcrypt20-dev zlib1g-dev
```

--------------------------------

### Start Ulfius Framework (Secure HTTPS)

Source: https://babelouest.github.io/ulfius/index.html

Starts the Ulfius web service for a secure HTTPS connection using a private key and server certificate. Accepts the instance, private key, and certificate as parameters.

```c
int ulfius_start_secure_framework(struct _u_instance * u_instance, const char * key_pem, const char * cert_pem);
```

--------------------------------

### Start Ulfius Secure Framework with CA Trust

Source: https://babelouest.github.io/ulfius/ulfius_8c.html

Starts the Ulfius framework with SSL/TLS and CA trust support. Requires key, certificate, and root CA PEM files.

```c
int ulfius_start_secure_ca_trust_framework(struct _u_instance *u_instance, const char *key_pem, const char *cert_pem, const char *root_ca_pem)
```

--------------------------------

### Install Ulfius Pre-compiled Package on Debian

Source: https://babelouest.github.io/ulfius/md_INSTALL.html

Installs Ulfius and its dependencies from a pre-compiled tarball on Debian. Ensure all required development files are installed first.

```bash
sudo apt install -y libmicrohttpd-dev libjansson-dev libcurl4-gnutls-dev libgnutls28-dev libgcrypt20-dev libsystemd-dev
```

```bash
wget https://github.com/babelouest/ulfius/releases/download/v2.7.0/ulfius-dev-full_2.7.0_debian_buster_x86_64.tar.gz
```

```bash
tar xf ulfius-dev-full_2.7.0_debian_buster_x86_64.tar.gz
```

```bash
sudo dpkg -i liborcania-dev_2.1.1_Debian_stretch_x86_64.deb
```

```bash
sudo dpkg -i libyder-dev_1.4.12_Debian_stretch_x86_64.deb
```

```bash
sudo dpkg -i libulfius-dev_2.7.0_Debian_stretch_x86_64.deb
```

--------------------------------

### Start Ulfius Framework (Secure HTTPS with Client CA Trust)

Source: https://babelouest.github.io/ulfius/index.html

Starts the Ulfius web service for a secure HTTPS connection, enabling client authentication with a certificate. Accepts the instance, private key, certificate, and root CA certificate.

```c
int ulfius_start_secure_ca_trust_framework(struct _u_instance * u_instance, const char * key_pem, const char * cert_pem, const char * root_ca_pem);
```

--------------------------------

### Build Ulfius using CMake

Source: https://babelouest.github.io/ulfius/md_INSTALL.html

Create a build directory, navigate into it, and run `cmake ..` followed by `make` and `sudo make install` to build Ulfius with CMake. Various options can be passed to `cmake` to configure the build.

```bash
mkdir build
cd build
cmake ..
$ make && sudo make install
```

--------------------------------

### Initialize Ulfius Instance

Source: https://babelouest.github.io/ulfius/ulfius_8c.html

Initializes a Ulfius instance with a specific port, bind address, and default authentication realm. This must be called before starting the framework.

```c
int ulfius_init_instance(struct _u_instance *u_instance, unsigned int port, struct sockaddr_in *bind_address, const char *default_auth_realm)
```

--------------------------------

### ulfius_start_secure_framework

Source: https://babelouest.github.io/ulfius/group__instance.html

Initializes the Ulfius framework and starts the web service using an HTTPS connection. Requires the server's private key and certificate in PEM format.

```APIDOC
## ulfius_start_secure_framework()

### Description
Initializes the framework and runs the webservice based on the parameters given using an HTTPS connection.

### Parameters
- **u_instance** (*struct _u_instance*): Pointer to a struct _u_instance that describes its port and bind address.
- **key_pem** (*const char*): The private key for the server in PEM format.
- **cert_pem** (*const char*): The server certificate in PEM format.

### Returns
- **int**: U_OK on success.
```

--------------------------------

### Framework Initialization and Control

Source: https://babelouest.github.io/ulfius/globals_u.html

Functions for initializing, starting, and stopping the Ulfius framework.

```APIDOC
## ulfius_global_close()

### Description
Closes global resources for the Ulfius framework.

### Source
ulfius.c, ulfius.h
```

```APIDOC
## ulfius_global_init()

### Description
Initializes global resources for the Ulfius framework.

### Source
ulfius.c, ulfius.h
```

```APIDOC
## ulfius_init_instance()

### Description
Initializes a Ulfius framework instance.

### Source
ulfius.c, ulfius.h
```

```APIDOC
## ulfius_start_framework()

### Description
Starts the Ulfius framework.

### Source
ulfius.c, ulfius.h
```

```APIDOC
## ulfius_start_framework_with_mhd_options()

### Description
Starts the Ulfius framework with custom MHD options.

### Source
ulfius.c, ulfius.h
```

```APIDOC
## ulfius_start_secure_ca_trust_framework()

### Description
Starts the Ulfius framework with secure CA trust.

### Source
ulfius.c, ulfius.h
```

```APIDOC
## ulfius_start_secure_framework()

### Description
Starts the Ulfius framework securely.

### Source
ulfius.c, ulfius.h
```

```APIDOC
## ulfius_stop_framework()

### Description
Stops the Ulfius framework.

### Source
ulfius.c, ulfius.h
```

--------------------------------

### Install Ulfius via Debian Package Manager

Source: https://babelouest.github.io/ulfius/md_INSTALL.html

Installs the Ulfius library with development files and uwsc on Debian-based systems. Use this for automatic package management.

```bash
sudo apt install libulfius-dev uwsc
```

```bash
sudo apt install uwsc
```

--------------------------------

### Framework Initialization and Control

Source: https://babelouest.github.io/ulfius/ulfius_8h_source.html

Functions for initializing, starting, stopping, and globally closing the Ulfius framework.

```APIDOC
## ulfius_global_init

### Description
Initializes the Ulfius global context.

### Function Signature
```c
int ulfius_global_init(void)
```
```

```APIDOC
## ulfius_global_close

### Description
Closes the Ulfius global context and frees associated resources.

### Function Signature
```c
void ulfius_global_close(void)
```
```

```APIDOC
## ulfius_start_framework

### Description
Starts the Ulfius web framework.

### Function Signature
```c
int ulfius_start_framework(struct _u_instance *u_instance)
```
```

```APIDOC
## ulfius_stop_framework

### Description
Stops the Ulfius web framework.

### Function Signature
```c
int ulfius_stop_framework(struct _u_instance *u_instance)
```
```

```APIDOC
## ulfius_start_secure_framework

### Description
Starts the Ulfius web framework with TLS/SSL enabled.

### Parameters
- **u_instance** (*struct _u_instance *): Pointer to the Ulfius instance.
- **key_pem** (*const char *): Path to the private key PEM file.
- **cert_pem** (*const char *): Path to the certificate PEM file.

### Function Signature
```c
int ulfius_start_secure_framework(struct _u_instance *u_instance, const char *key_pem, const char *cert_pem)
```
```

```APIDOC
## ulfius_start_secure_ca_trust_framework

### Description
Starts the Ulfius web framework with TLS/SSL enabled, including CA trust configuration.

### Parameters
- **u_instance** (*struct _u_instance *): Pointer to the Ulfius instance.
- **key_pem** (*const char *): Path to the private key PEM file.
- **cert_pem** (*const char *): Path to the certificate PEM file.
- **root_ca_pem** (*const char *): Path to the root CA certificate PEM file.

### Function Signature
```c
int ulfius_start_secure_ca_trust_framework(struct _u_instance *u_instance, const char *key_pem, const char *cert_pem, const char *root_ca_pem)
```
```

--------------------------------

### Framework Lifecycle Management

Source: https://babelouest.github.io/ulfius/ulfius_8h.html

Functions to start and stop the Ulfius web framework.

```APIDOC
## Framework Lifecycle

### `ulfius_start_framework`
Starts the Ulfius web framework for a given instance.

### `ulfius_start_secure_framework`
Starts the Ulfius web framework securely using provided key and certificate PEM files.

### `ulfius_start_secure_ca_trust_framework`
Starts the Ulfius web framework securely with CA trust using provided key, certificate, and root CA PEM files.

### `ulfius_start_framework_with_mhd_options`
Starts the Ulfius web framework with custom MicroHTTPD options.

### `ulfius_stop_framework`
Stops the Ulfius web framework for a given instance.
```

--------------------------------

### Initialize WebSocket Extension

Source: https://babelouest.github.io/ulfius/u__private_8h_source.html

Initializes a WebSocket extension structure. This is an internal function used during WebSocket setup.

```APIDOC
## ulfius_init_websocket_extension

### Description
Initializes a WebSocket extension structure. This is an internal function used during WebSocket setup.

### Function Signature
`int ulfius_init_websocket_extension(struct _websocket_extension * websocket_extension);`

### Parameters
* **websocket_extension** (struct _websocket_extension *) - A pointer to the WebSocket extension to initialize.

### Returns
Returns 0 on success, or an error code on failure.
```

--------------------------------

### ulfius_start_secure_ca_trust_framework

Source: https://babelouest.github.io/ulfius/group__instance.html

Initializes the Ulfius framework and starts the web service using an HTTPS connection with CA trust. Requires the server's private key, certificate, and root CA certificate in PEM format.

```APIDOC
## ulfius_start_secure_ca_trust_framework()

### Description
Initializes the framework and runs the webservice based on the parameters given using an HTTPS connection with CA trust.

### Parameters
- **u_instance** (*struct _u_instance*): Pointer to a struct _u_instance that describes its port and bind address.
- **key_pem** (*const char*): The private key for the server in PEM format.
- **cert_pem** (*const char*): The server certificate in PEM format.
- **root_ca_pem** (*const char*): The root CA certificate in PEM format.

### Returns
- **int**: U_OK on success.
```

--------------------------------

### Initialize WebSocket

Source: https://babelouest.github.io/ulfius/u__private_8h_source.html

Initializes a WebSocket structure. This is an internal function used during WebSocket setup.

```APIDOC
## ulfius_init_websocket

### Description
Initializes a WebSocket structure. This is an internal function used during WebSocket setup.

### Function Signature
`int ulfius_init_websocket(struct _websocket * websocket);`

### Parameters
* **websocket** (struct _websocket *) - A pointer to the WebSocket structure to initialize.

### Returns
Returns 0 on success, or an error code on failure.
```

--------------------------------

### WebSocket Callback Function Declaration

Source: https://babelouest.github.io/ulfius/u__private_8h_source.html

Declares the callback function for starting a WebSocket connection.

```c
void ulfius_start_websocket_cb (void *cls,
struct MHD_Connection *connection,
void *con_cls,
const char *extra_in,
size_t extra_in_size,
MHD_socket sock,
struct MHD_UpgradeResponseHandle *urh);
```

--------------------------------

### WebSocket Connection and Message Handling

Source: https://babelouest.github.io/ulfius/u__websocket_8c.html

Functions for initializing, starting, and managing WebSocket connections and messages.

```APIDOC
## ulfius_start_websocket_cb

### Description
Callback function to start a WebSocket connection.

### Signature
`void ulfius_start_websocket_cb(void *cls, struct MHD_Connection *connection, void *con_cls, const char *extra_in, size_t extra_in_size, MHD_socket sock, struct MHD_UpgradeResponseHandle *urh)`

## ulfius_init_websocket_message_list

### Description
Initializes a list for WebSocket messages.

### Signature
`int ulfius_init_websocket_message_list(struct _websocket_message_list *message_list)`

## ulfius_push_websocket_message

### Description
Pushes a WebSocket message onto a list.

### Signature
`int ulfius_push_websocket_message(struct _websocket_message_list *message_list, struct _websocket_message *message)`

## ulfius_close_websocket

### Description
Closes a WebSocket connection.

### Signature
`int ulfius_close_websocket(struct _websocket *websocket)`

## ulfius_instance_add_websocket_active

### Description
Adds an active WebSocket to the instance.

### Signature
`int ulfius_instance_add_websocket_active(struct _u_instance *instance, struct _websocket *websocket)`

## ulfius_instance_remove_websocket_active

### Description
Removes an active WebSocket from the instance.

### Signature
`int ulfius_instance_remove_websocket_active(struct _u_instance *instance, struct _websocket *websocket)`

## ulfius_websocket_send_fragmented_message

### Description
Sends a fragmented WebSocket message.

### Signature
`int ulfius_websocket_send_fragmented_message(struct _websocket_manager *websocket_manager, const uint8_t opcode, const uint64_t data_len, const char *data, const uint64_t fragment_len)`

## ulfius_websocket_send_message

### Description
Sends a WebSocket message.

### Signature
`int ulfius_websocket_send_message(struct _websocket_manager *websocket_manager, const uint8_t opcode, const uint64_t data_len, const char *data)`

## ulfius_websocket_send_json_message

### Description
Sends a JSON message over WebSocket.

### Signature
`int ulfius_websocket_send_json_message(struct _websocket_manager *websocket_manager, json_t *j_message)`

## ulfius_websocket_parse_json_message

### Description
Parses a JSON message received over WebSocket.

### Signature
`json_t * ulfius_websocket_parse_json_message(const struct _websocket_message *message, json_error_t *json_error)`

## ulfius_websocket_pop_first_message

### Description
Pops the first WebSocket message from a list.

### Signature
`struct _websocket_message * ulfius_websocket_pop_first_message(struct _websocket_message_list *message_list)`

## ulfius_clear_websocket_message

### Description
Clears a WebSocket message.

### Signature
`void ulfius_clear_websocket_message(struct _websocket_message *message)`

## ulfius_clear_websocket

### Description
Clears a WebSocket connection.

### Signature
`int ulfius_clear_websocket(struct _websocket *websocket)`

## ulfius_clear_websocket_message_list

### Description
Clears a list of WebSocket messages.

### Signature
`void ulfius_clear_websocket_message_list(struct _websocket_message_list *message_list)`

## ulfius_init_websocket

### Description
Initializes a WebSocket connection.

### Signature
`int ulfius_init_websocket(struct _websocket *websocket)`

## ulfius_init_websocket_manager

### Description
Initializes a WebSocket manager.

### Signature
`int ulfius_init_websocket_manager(struct _websocket_manager *websocket_manager)`

## ulfius_clear_websocket_manager

### Description
Clears a WebSocket manager.

### Signature
`void ulfius_clear_websocket_manager(struct _websocket_manager *websocket_manager)`

## ulfius_set_websocket_response

### Description
Sets up a response to handle WebSocket connections, including callbacks for manager, incoming messages, and closure.

### Signature
`int ulfius_set_websocket_response(struct _u_response *response, const char *websocket_protocol, const char *websocket_extensions, void(*websocket_manager_callback)(const struct _u_request *request, struct _websocket_manager *websocket_manager, void *websocket_manager_user_data), void *websocket_manager_user_data, void(*websocket_incoming_message_callback)(const struct _u_request *request, struct _websocket_manager *websocket_manager, const struct _websocket_message *message, void *websocket_incoming_user_data), void *websocket_incoming_user_data, void(*websocket_onclose_callback)(const struct _u_request *request, struct _websocket_manager *websocket_manager, void *websocket_onclose_user_data), void *websocket_onclose_user_data)`
```

--------------------------------

### Handle Binary File Upload in Ulfius

Source: https://babelouest.github.io/ulfius/index.html

Example of a callback function to process uploaded files, specifically handling binary data by disabling UTF-8 checks and using `u_map_get_length` to determine file size.

```c
int callback_function(const struct _u_request * request, struct _u_response * response, void * user_data) {
const char * file_data = u_map_get(request->map_post_body, "file_parameter");
size_t file_size = u_map_get_length(request->map_post_body, "file_parameter");
// process http request
// [...]
return U_CALLBACK_CONTINUE;
}
```

```c
int main() {
// initialize instance
struct _u_instance u_instance;
ulfius_init_instance(&u_instance, 8080, NULL, NULL);
u_instance.check_utf8 = 0;
ulfius_add_endpoint_by_val(&u_instance, "POST", "/upload", NULL, 0, &callback_function, NULL);
ulfius_start_framework(&u_instance);
// The program continues...
}
```

--------------------------------

### Framework Configuration and Startup Functions

Source: https://babelouest.github.io/ulfius/globals_func_u.html

Functions for setting default endpoints, request properties, upload callbacks, and starting/stopping the Ulfius framework.

```APIDOC
## ulfius_set_default_endpoint()

### Description
Sets the default endpoint for the Ulfius framework.

### Method
(Not specified in source)

### Endpoint
(Not specified in source)

### Parameters
(Not specified in source)

### Request Example
(Not specified in source)

### Response
(Not specified in source)
```

```APIDOC
## ulfius_set_request_properties()

### Description
Sets properties for an HTTP request.

### Method
(Not specified in source)

### Endpoint
(Not specified in source)

### Parameters
(Not specified in source)

### Request Example
(Not specified in source)

### Response
(Not specified in source)
```

```APIDOC
## ulfius_set_upload_file_callback_function()

### Description
Sets a callback function to handle file uploads.

### Method
(Not specified in source)

### Endpoint
(Not specified in source)

### Parameters
(Not specified in source)

### Request Example
(Not specified in source)

### Response
(Not specified in source)
```

```APIDOC
## ulfius_start_framework()

### Description
Starts the Ulfius framework.

### Method
(Not specified in source)

### Endpoint
(Not specified in source)

### Parameters
(Not specified in source)

### Request Example
(Not specified in source)

### Response
(Not specified in source)
```

```APIDOC
## ulfius_start_framework_with_mhd_options()

### Description
Starts the Ulfius framework with Microhttpd options.

### Method
(Not specified in source)

### Endpoint
(Not specified in source)

### Parameters
(Not specified in source)

### Request Example
(Not specified in source)

### Response
(Not specified in source)
```

```APIDOC
## ulfius_start_secure_ca_trust_framework()

### Description
Starts the Ulfius framework with secure CA trust.

### Method
(Not specified in source)

### Endpoint
(Not specified in source)

### Parameters
(Not specified in source)

### Request Example
(Not specified in source)

### Response
(Not specified in source)
```

```APIDOC
## ulfius_start_secure_framework()

### Description
Starts the Ulfius framework securely.

### Method
(Not specified in source)

### Endpoint
(Not specified in source)

### Parameters
(Not specified in source)

### Request Example
(Not specified in source)

### Response
(Not specified in source)
```

```APIDOC
## ulfius_stop_framework()

### Description
Stops the Ulfius framework.

### Method
(Not specified in source)

### Endpoint
(Not specified in source)

### Parameters
(Not specified in source)

### Request Example
(Not specified in source)

### Response
(Not specified in source)
```

--------------------------------

### ulfius_start_framework_with_mhd_options

Source: https://babelouest.github.io/ulfius/group__instance.html

Initializes the Ulfius framework with custom MicroHTTPD options, allowing for advanced configuration of the web service. Use with caution as incorrect options may cause issues.

```APIDOC
## ulfius_start_framework_with_mhd_options()

### Description
Initializes the framework and runs the webservice based on the specified MHD options table. This is for advanced users familiar with libmicrohttpd.

### Parameters
- **_u_instance** (struct _u_instance *) - Pointer to a struct _u_instance that describes its port and bind address.
- **_mhd_flags** (unsigned int) - OR-ed combination of MHD_FLAG values.
- **_mhd_ops** (struct MHD_OptionItem *) - Options table. Must contain MHD_OPTION_NOTIFY_COMPLETED, MHD_OPTION_URI_LOG_CALLBACK, and end with MHD_OPTION_END.

### Returns
- U_OK on success.
```

--------------------------------

### ulfius_init_websocket

Source: https://babelouest.github.io/ulfius/u__private_8h.html

Initialize a struct _websocket. Return U_OK on success.

```APIDOC
## ulfius_init_websocket()

### Description
Initialize a struct _websocket. Return U_OK on success.

### Signature
int ulfius_init_websocket(struct _websocket * _websocket)
```

--------------------------------

### Framework Control

Source: https://babelouest.github.io/ulfius/ulfius_8h_source.html

Functions for starting and stopping the Ulfius framework.

```APIDOC
## ulfius_start_framework

### Description
Starts the Ulfius framework for a given instance.

### Function Signature
```c
int ulfius_start_framework(struct _u_instance * u_instance);
```

## ulfius_start_secure_framework

### Description
Starts the Ulfius framework securely using provided key and certificate.

### Function Signature
```c
int ulfius_start_secure_framework(struct _u_instance * u_instance, const char * key_pem, const char * cert_pem);
```

## ulfius_start_secure_ca_trust_framework

### Description
Starts the Ulfius framework securely with CA trust support.

### Function Signature
```c
int ulfius_start_secure_ca_trust_framework(struct _u_instance * u_instance, const char * key_pem, const char * cert_pem, const char * root_ca_pem);
```

## ulfius_start_framework_with_mhd_options

### Description
Starts the Ulfius framework with custom libmicrohttpd options.

### Function Signature
```c
int ulfius_start_framework_with_mhd_options(struct _u_instance * u_instance, unsigned int mhd_flags, struct MHD_OptionItem * mhd_ops);
```

## ulfius_stop_framework

### Description
Stops the Ulfius framework for a given instance.

### Function Signature
```c
int ulfius_stop_framework(struct _u_instance * u_instance);
```
```

--------------------------------

### ulfius_init_websocket_extension

Source: https://babelouest.github.io/ulfius/u__private_8h.html

Initializes a websocket extension structure. Returns U_OK on success.

```APIDOC
## Function: ulfius_init_websocket_extension

### Description
Initializes a websocket extension structure. Returns U_OK on success.

### Parameters
- `_websocket_extension_` (struct _websocket_extension *) - A pointer to the websocket extension to initialize.

### Returns
- `int` - U_OK on success, otherwise an error code.
```

--------------------------------

### File Uploads and Instance Initialization

Source: https://babelouest.github.io/ulfius/ulfius_8c.html

Functions for setting up file upload callbacks and initializing Ulfius instances.

```APIDOC
## ulfius_set_upload_file_callback_function()

### Description
Sets the callback function to handle file uploads.

### Method
int

### Parameters
- **u_instance** (*struct _u_instance* *) - Pointer to the Ulfius instance.
- **file_upload_callback** (*int(*)(const struct _u_request *, const char *, const char *, const char *, const char *, const char *, uint64_t, size_t, void *)*) - The callback function for file uploads.
- **cls** (*void* *) - User-defined data to pass to the callback.

### Return Value
Returns 0 on success, -1 on error.
```

```APIDOC
## ulfius_init_instance()

### Description
Initializes a Ulfius instance.

### Method
int

### Parameters
- **u_instance** (*struct _u_instance* *) - Pointer to the Ulfius instance to initialize.
- **port** (*unsigned int*) - The port number for the instance.
- **bind_address** (*struct sockaddr_in* *) - The address to bind to.
- **default_auth_realm** (*const char* *) - The default authentication realm.

### Return Value
Returns 0 on success, -1 on error.
```

--------------------------------

### JSON Body Handling

Source: https://babelouest.github.io/ulfius/ulfius_8h_source.html

Functions for getting and setting JSON bodies for requests and responses.

```APIDOC
## ulfius_get_json_body_request

### Description
Retrieves the JSON body from an HTTP request.

### Parameters
- **request** (*const struct _u_request *)
- **json_error** (*json_error_t *)

### Returns
A pointer to the JSON object representing the request body, or NULL on error.

## ulfius_set_json_body_request

### Description
Sets the JSON body for an HTTP request.

### Parameters
- **request** (*struct _u_request *)
- **j_body** (*json_t *)

## ulfius_get_json_body_response

### Description
Retrieves the JSON body from an HTTP response.

### Parameters
- **response** (*struct _u_response *)
- **json_error** (*json_error_t *)

### Returns
A pointer to the JSON object representing the response body, or NULL on error.

## ulfius_set_json_body_response

### Description
Sets the JSON body for an HTTP response with a specified status code.

### Parameters
- **response** (*struct _u_response *)
- **status** (*const unsigned int *)
- **j_body** (*const json_t *)

```

--------------------------------

### ulfius_init_websocket_manager

Source: https://babelouest.github.io/ulfius/u__private_8h.html

Initialize a struct _websocket_manager. Return U_OK on success.

```APIDOC
## ulfius_init_websocket_manager()

### Description
Initialize a struct _websocket_manager. Return U_OK on success.

### Signature
int ulfius_init_websocket_manager(struct _websocket_manager * _websocket_manager)
```

--------------------------------

### ulfius_init_websocket_message_list

Source: https://babelouest.github.io/ulfius/u__private_8h.html

Initialize a websocket message list. Return U_OK on success.

```APIDOC
## ulfius_init_websocket_message_list()

### Description
Initialize a websocket message list. Return U_OK on success.

### Signature
int ulfius_init_websocket_message_list(struct _websocket_message_list * _message_list)
```

--------------------------------

### Get Empty Endpoint

Source: https://babelouest.github.io/ulfius/ulfius_8c.html

Returns a pointer to a static, empty endpoint structure. Useful for initialization or comparison.

```c
const struct _u_endpoint *ulfius_empty_endpoint(void)
```

--------------------------------

### Get Ulfius Compile Flags with pkg-config

Source: https://babelouest.github.io/ulfius/index.html

Use pkg-config to retrieve the necessary compile flags for the libulfius library.

```bash
$ pkg-config --cflags libulfius
-I/usr/include
```

--------------------------------

### ulfius_start_websocket_cb

Source: https://babelouest.github.io/ulfius/u__private_8h.html

Callback function for MHD to start the websocket manager and handle messages. It manages the websocket lifecycle, closing it on various events.

```APIDOC
## Function: ulfius_start_websocket_cb

### Description
Callback function for MHD to start the websocket manager and handle messages. It manages the websocket lifecycle, closing it on various events.

### Parameters
- `_cls_` (void *) - User-defined context.
- `_connection_` (struct MHD_Connection *) - The current connection.
- `_con_cls_` (void *) - Connection-specific context.
- `_extra_in_` (const char *) - Incoming extra data.
- `_extra_in_size_` (size_t) - Size of the incoming extra data.
- `_sock_` (MHD_socket) - The socket associated with the connection.
- `_urh_` (struct MHD_UpgradeResponseHandle *) - Handle for upgrade response.
```

--------------------------------

### Initialization and Cleanup

Source: https://babelouest.github.io/ulfius/ulfius_8h.html

Functions for initializing and closing the Ulfius framework globally and for specific instances.

```APIDOC
## Global Initialization and Cleanup

### `ulfius_global_init`
Initializes the Ulfius framework globally.

### `ulfius_global_close`
Closes the Ulfius framework globally.

### `ulfius_init_instance`
Initializes a specific Ulfius instance with a port, bind address, and default authentication realm.

### `ulfius_clean_instance`
Cleans up a specific Ulfius instance.

### `u_free`
Frees memory allocated by Ulfius.
```

--------------------------------

### Get JSON body from response

Source: https://babelouest.github.io/ulfius/index.html

Use this function to retrieve the JSON body from a response. Ensure JSON is enabled during Ulfius build.

```c
json_t * ulfius_get_json_body_response(struct _u_response * response, json_error_t * json_error);
```

--------------------------------

### ulfius_init_instance

Source: https://babelouest.github.io/ulfius/group__instance.html

Initializes a Ulfius instance with default values and binds it to a specified IPv4 address and port. It also sets a default realm for authentication errors.

```APIDOC
## ulfius_init_instance()

### Description
Initialize a struct _u_instance * with default values. Binds to IPV4 addresses only.

### Parameters
- **u_instance** (*struct _u_instance*): The Ulfius instance to initialize.
- **port** (*unsigned int*): The TCP port to bind to. Must be between 1 and 65535.
- **bind_address** (*struct sockaddr_in*): The IPv4 address to listen to. This is optional, and the reference is borrowed; the structure isn't copied.
- **default_auth_realm** (*const char*): The default realm to send to the client on authentication error.

### Returns
- **int**: U_OK on success.
```

--------------------------------

### Get Ulfius Linker Flags with pkg-config

Source: https://babelouest.github.io/ulfius/index.html

Use pkg-config to retrieve the necessary linker flags for the libulfius library, including its dependencies.

```bash
$ pkg-config --libs libulfius
-L/usr/lib -lulfius -lorcania -lyder
```

--------------------------------

### ulfius_init_request

Source: https://babelouest.github.io/ulfius/ulfius_8h.html

Initializes a request object.

```APIDOC
## ulfius_init_request

### Description
Initializes a request object.

### Parameters
- **request** (*struct _u_request* *) - Pointer to the request object to initialize.

### Return Value
Returns 0 on success, or a negative value on error.
```

--------------------------------

### Global Initialization

Source: https://babelouest.github.io/ulfius/ulfius_8c.html

Performs global initialization for the Ulfius library. Should be called once at the beginning of the application.

```c
int ulfius_global_init(void)
```

--------------------------------

### Global Initialization and Cleanup

Source: https://babelouest.github.io/ulfius/ulfius_8c.html

Functions for global initialization and cleanup of the Ulfius library.

```APIDOC
## ulfius_global_init()

### Description
Performs global initialization for the Ulfius library.

### Method
int

### Return Value
Returns 0 on success, -1 on error.
```

```APIDOC
## ulfius_global_close()

### Description
Performs global cleanup for the Ulfius library.

### Method
void

```

--------------------------------

### Get Websocket Client Connection Status

Source: https://babelouest.github.io/ulfius/index.html

Retrieves the current status of the websocket client connection. This is useful for monitoring the connection's health.

```c
int ulfius_websocket_client_connection_status(struct _websocket_client_handler *websocket_client_handler);
```

--------------------------------

### u_map_init

Source: https://babelouest.github.io/ulfius/ulfius_8h.html

Initializes a map (key-value store) object.

```APIDOC
## u_map_init

### Description
Initializes a map (key-value store) object.

### Parameters
- **u_map** (*struct _u_map* *) - Pointer to the map object to initialize.

### Return Value
Returns 0 on success, or a negative value on error.
```

--------------------------------

### Get Ulfius websocket connection status

Source: https://babelouest.github.io/ulfius/index.html

Checks the current status of the websocket connection. This function can be used to determine if the websocket is still open.

```c
int ulfius_websocket_status(struct _websocket_manager * websocket_manager);
```

```c
int ulfius_websocket_status(struct _websocket_manager *websocket_manager)
{
    // Implementation details
    return 0; // Placeholder
}
```

--------------------------------

### Get JSON body from request

Source: https://babelouest.github.io/ulfius/index.html

Use this function to retrieve the JSON body from an incoming request. Ensure JSON is enabled during Ulfius build.

```c
json_t * ulfius_get_json_body_request(const struct _u_request * request, json_error_t * json_error);
```

--------------------------------

### ulfius_init_websocket_extension

Source: https://babelouest.github.io/ulfius/u__private_8h_source.html

Initializes a WebSocket extension structure. This prepares an extension object for use with WebSockets.

```APIDOC
## ulfius_init_websocket_extension

### Description
Initializes a WebSocket extension.

### Signature
```c
int ulfius_init_websocket_extension(struct _websocket_extension *websocket_extension)
```
```

--------------------------------

### Check First Match

Source: https://babelouest.github.io/ulfius/u__private_8h_source.html

Checks if a source string starts with a match from a list of items separated by a delimiter. Returns the first matched item if found.

```APIDOC
## ulfius_check_first_match

### Description
Checks if a source string starts with a match from a list of items separated by a delimiter. Returns the first matched item if found.

### Function Signature
`int ulfius_check_first_match(const char * source, const char * match, const char * separator, char ** result);`

### Parameters
* **source** (const char *) - The string to check.
* **match** (const char *) - The item to match against.
* **separator** (const char *) - The delimiter used in the source string.
* **result** (char **) - A pointer to a char pointer that will store the matched item if found.

### Returns
Returns 0 on success, or an error code on failure. The matched item is stored in `result`.
```

--------------------------------

### Access POST parameter in callback

Source: https://babelouest.github.io/ulfius/index.html

Example of how to access a POST parameter within a callback function using the `u_map_get` function. Parameter keys are case-sensitive.

```c
int callback_test (const struct _u_request * request, struct _u_response * response, void * user_data) {
printf("POST parameter id: %s\n", u_map_get(request->map_post_body, "id"));
return U_CALLBACK_CONTINUE;
}
```