Ulfius: Ulfius API Documentation

Ulfius HTTP Framework for REST Applications in C

Ulfius API Documentation

- Use Ulfius in a C program
  - Header file
  - Build options
- Return values
- Memory management
- Webservice initialization
  - Instance structure
  - Endpoint structure
  - Multiple callback functions
  - Multiple URLs with similar pattern
- Start and stop webservice
- Callback functions management
  - Request structure
    - ulfius_set_request_properties
  - Response structure
    - ulfius_set_response_properties
  - Callback functions return value
  - Use JSON in request and response body
  - Additional functions
  - Memory management
  - Character encoding
  - Accessing POST parameters
  - Accessing query string and URL parameters
  - Accessing header parameters
  - Cookie management
  - File upload
    - Binary file upload
  - Streaming data
  - Websockets communication
    - Websocket management
    - Messages manipulation
    - Server-side websocket
      - Open a websocket communication
      - Advanced websocket extension
      - Built-in server extension permessage-deflate
      - Close a websocket communication
      - Websocket status
    - Client-side websocket
      - Prepare the request
      - Built-in client extension permessage-deflate
      - Open the websocket
      - Client Websocket status
- Outgoing request functions
  - Send HTTP request API
  - Send SMTP request API
- struct _u_map API
- What's new in Ulfius 2.7?
- What's new in Ulfius 2.6?
- What's new in Ulfius 2.5?
- What's new in Ulfius 2.4?
- What's new in Ulfius 2.3?
- What's new in Ulfius 2.2?
- What's new in Ulfius 2.1?
- What's new in Ulfius 2.0?
  - Multiple callback functions
  - Keep only binary_body in struct _u_request and struct _u_response
  - Websocket service
  - Remove libjansson and libcurl hard dependency
  - Ready-to-use callback functions
- Update existing programs from Ulfius 2.0 to 2.1
- Update existing programs from Ulfius 1.x to 2.0

# Use Ulfius in a C program

## Header file

Include file ulfius.h in your source file:

#include <ulfius.h>
ulfius.h
Ulfius framework.

## Build options

You can use pkg-config to provide the compile and link options for Ulfius:

$ # compile flags
$ pkg-config --cflags libulfius
-I/usr/include
$ # linker flags
$ pkg-config --libs libulfius
-L/usr/lib -lulfius -lorcania -lyder

If you don't or can't have pkg-config for the build, you can set the linker options -lulfius -lorcania -lyder.

The options -lorcania and -lyder are not necessary if you don't directly use Orcania or Yder functions. But in doubt, add them anyway.

On your linker command, add Ulfius as a dependency library, e.g. -lulfius for gcc.

# Return values

When specified, some functions return U_OK on success, and other values otherwise. U_OK is 0, other values are non-0 values. The defined return value list is the following:

#define U_OK 0 // No error
#define U_ERROR 1 // Error
#define U_ERROR_MEMORY 2 // Error in memory allocation
#define U_ERROR_PARAMS 3 // Error in input parameters
#define U_ERROR_LIBMHD 4 // Error in libmicrohttpd execution
#define U_ERROR_LIBCURL 5 // Error in libcurl execution
#define U_ERROR_NOT_FOUND 6 // Something was not found

# Memory management

Ulfius uses the memory allocation functions malloc/realloc/calloc/free by default, but you can overwrite this and use any other memory allocation functions of your choice. Use Orcania's functions o_set_alloc_funcs and o_get_alloc_funcs to set and get memory allocation functions.

void o_set_alloc_funcs(o_malloc_t malloc_fn, o_realloc_t realloc_fn, o_free_t free_fn);
void o_get_alloc_funcs(o_malloc_t * malloc_fn, o_realloc_t * realloc_fn, o_free_t * free_fn);

Accessing those functions requires you to directly link your application also against the Orcania library. To do so, add -lorcania to your linking command.

If you use a version of libmicrohttpd older than 0.9.61, you need to set the mhd_response_copy_data = 1 in your _u_instance if you use a memory allocator whose allocated return values may not directly be passed to free() or if you want to make sure all free() will always go via your user-provided free callback.

Data structures allocated have their specific cleanup functions. To free pointer allocated, you should use the function u_free that is intended to use your memory management functions.

void ulfius_clean_instance(struct _u_instance * u_instance);
int ulfius_clean_request(struct _u_request * request);
int ulfius_clean_response(struct _u_response * response);
int u_map_clean(struct _u_map * u_map);
void u_free(void * data);
ulfius_clean_instance
void ulfius_clean_instance(struct _u_instance *u_instance)
Definition ulfius.c:1624
u_free
void u_free(void *data)
Definition ulfius.c:1746
ulfius_clean_response
int ulfius_clean_response(struct _u_response *response)
Definition u_response.c:332
ulfius_clean_request
int ulfius_clean_request(struct _u_request *request)
Definition u_request.c:323
u_map_clean
int u_map_clean(struct _u_map *u_map)
Definition u_map.c:70
_u_instance
Contains the needed data for an ulfius instance to work.
Definition ulfius.h:316
_u_map
Definition ulfius.h:204
_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

It's recommended to use ulfius_global_init and ulfius_global_close at the beginning and at the end of your program to initialize and cleanup internal values and settings. This will make outgoing requests faster, especially if you use lots of them, and dispatch your memory allocation functions in curl and Jansson if you changed them. These functions are NOT thread-safe, so you must use them in a single thread context.

int ulfius_global_init();
void ulfius_global_close();
ulfius_global_close
void ulfius_global_close(void)
Definition ulfius.c:1930
ulfius_global_init
int ulfius_global_init(void)
Definition ulfius.c:1906

# Webservice initialization

Ulfius framework runs as an async task in the background. When initialized, a thread is executed in the background. This thread will listen to the specified port and dispatch the calls to the specified callback functions. Ulfius allows adding and removing new endpoints during the instance execution.

To run a webservice, you must initialize a Structures _u_instance and add your endpoints.

## Instance structure

The Structures _u_instance is defined as:

struct _u_instance {
struct MHD_Daemon * mhd_daemon;
int status;
unsigned int port;
#if MHD_VERSION >= 0x00095208
unsigned short network_type;
#endif
struct sockaddr_in * bind_address;
struct sockaddr_in6 * bind_address6;
unsigned int timeout;
int nb_endpoints;
char * default_auth_realm;
struct _u_endpoint * endpoint_list;
struct _u_endpoint * default_endpoint;
struct _u_map * default_headers;
size_t max_post_param_size;
size_t max_post_body_size;
void * websocket_handler;
int (* file_upload_callback) (const struct _u_request * request,
const char * key,
const char * filename,
const char * content_type,
const char * transfer_encoding,
const char * data,
uint64_t off,
size_t size,
void * cls);
void * file_upload_cls;
int mhd_response_copy_data;
int check_utf8;
#ifndef U_DISABLE_GNUTLS
int use_client_cert_auth;
#endif
int allowed_post_processor;
};
_u_endpoint
Contains all informations needed for an endpoint.
Definition ulfius.h:299
_u_instance::status
int status
Definition ulfius.h:318
_u_instance::max_post_param_size
size_t max_post_param_size
Definition ulfius.h:331
_u_instance::mhd_daemon
struct MHD_Daemon * mhd_daemon
Definition ulfius.h:317
_u_instance::allowed_post_processor
int allowed_post_processor
Definition ulfius.h:349
_u_instance::port
unsigned int port
Definition ulfius.h:319
_u_instance::timeout
unsigned int timeout
Definition ulfius.h:325
_u_instance::max_post_body_size
size_t max_post_body_size
Definition ulfius.h:332
_u_instance::bind_address
struct sockaddr_in * bind_address
Definition ulfius.h:323
_u_instance::file_upload_cls
void * file_upload_cls
Definition ulfius.h:343
_u_instance::default_headers
struct _u_map * default_headers
Definition ulfius.h:330
_u_instance::check_utf8
int check_utf8
Definition ulfius.h:345
_u_instance::bind_address6
struct sockaddr_in6 * bind_address6
Definition ulfius.h:324
_u_instance::endpoint_list
struct _u_endpoint * endpoint_list
Definition ulfius.h:328
_u_instance::nb_endpoints
int nb_endpoints
Definition ulfius.h:326
_u_instance::default_endpoint
struct _u_endpoint * default_endpoint
Definition ulfius.h:329
_u_instance::websocket_handler
void * websocket_handler
Definition ulfius.h:333
_u_instance::file_upload_callback
int(* file_upload_callback)(const struct _u_request *request, const char *key, const char *filename, const char *content_type, const char *transfer_encoding, const char *data, uint64_t off, size_t size, void *cls)
Definition ulfius.h:334
_u_instance::default_auth_realm
char * default_auth_realm
Definition ulfius.h:327
_u_instance::mhd_response_copy_data
int mhd_response_copy_data
Definition ulfius.h:344
_u_instance::use_client_cert_auth
int use_client_cert_auth
Definition ulfius.h:347

In the Structures _u_instance structure, the element port must be set to the port number you want to listen to, the element bind_address is used if you want to listen only to a specific IP address. The element mhd_daemon is used by the framework, don't modify it.

You can use the functions ulfius_init_instance, ulfius_init_instance_ipv6 and ulfius_clean_instance to facilitate the manipulation of the structure:

int ulfius_init_instance(struct _u_instance * u_instance, unsigned int port, struct sockaddr_in * bind_address, const char * default_auth_realm);
int ulfius_init_instance_ipv6(struct _u_instance * u_instance, unsigned int port, struct sockaddr_in6 * bind_address, unsigned short network_type, const char * default_auth_realm);
void ulfius_clean_instance(struct _u_instance * u_instance);
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

Since Ulfius 2.6, you can bind to IPv4 connections, IPv6 or both. By default, ulfius_init_instance binds to IPv4 addresses only. If you want to bind to both IPv4 and IPv6 addresses, use ulfius_init_instance_ipv6 with the value parameter network_type set to U_USE_ALL. If you want to bind to IPv6 addresses only, use ulfius_init_instance_ipv6 with the value parameter network_type set to U_USE_IPV6.

If you bind your instance to an address, you MUST set the port number to Structures sockaddr_in.sport because the Structures _u_instance.port will be ignored.

## Endpoint structure

The Structures _u_endpoint is defined as:

struct _u_endpoint {
char * http_method;
char * url_prefix;
char * url_format;
unsigned int priority;
int (* callback_function)(const struct _u_request * request, // Input parameters (set by the framework)
struct _u_response * response, // Output parameters (set by the user)
void * user_data);
void * user_data;
};
_u_endpoint::callback_function
int(* callback_function)(const struct _u_request *request, struct _u_response *response, void *user_data)
Definition ulfius.h:304
_u_endpoint::user_data
void * user_data
Definition ulfius.h:307
_u_endpoint::priority
unsigned int priority
Definition ulfius.h:303
_u_endpoint::http_method
char * http_method
Definition ulfius.h:300
_u_endpoint::url_format
char * url_format
Definition ulfius.h:302
_u_endpoint::url_prefix
char * url_prefix
Definition ulfius.h:301

Some functions help you facilitate endpoints manipulation:

int ulfius_add_endpoint(struct _u_instance * u_instance, const struct _u_endpoint * u_endpoint);
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, // Input parameters (set by the framework)
struct _u_response * response, // Output parameters (set by the user)
void * user_data),
void * user_data);
int ulfius_add_endpoint_list(struct _u_instance * u_instance, const struct _u_endpoint ** u_endpoint_list);
int ulfius_remove_endpoint(struct _u_instance * u_instance, const struct _u_endpoint * u_endpoint);
int ulfius_remove_endpoint_by_val(struct _u_instance * u_instance, const char * http_method, const char * url_prefix, const char * url_format);
int ulfius_set_default_callback_function(struct _u_instance * u_instance,
int (* callback_function)(const struct _u_request * request, struct _u_response * response, void * user_data),
void * user_data);
ulfius_add_endpoint_list
int ulfius_add_endpoint_list(struct _u_instance *u_instance, const struct _u_endpoint **u_endpoint_list)
Definition ulfius.c:1445
ulfius_add_endpoint
int ulfius_add_endpoint(struct _u_instance *u_instance, const struct _u_endpoint *u_endpoint)
Definition ulfius.c:1405
ulfius_remove_endpoint
int ulfius_remove_endpoint(struct _u_instance *u_instance, const struct _u_endpoint *u_endpoint)
Definition ulfius.c:1462
ulfius_remove_endpoint_by_val
int ulfius_remove_endpoint_by_val(struct _u_instance *u_instance, const char *http_method, const char *url_prefix, const char *url_format)
Definition ulfius.c:1568
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

HTTP Method can be an existing or not existing method, or * for any method. You must specify a url_prefix, a url_format or both, callback_function is mandatory, user_data is optional.

If you fill your array of endpoints manually, your Structures _u_endpoint array MUST end with an empty Structures _u_endpoint.

You can manually declare an endpoint or use the dedicated functions as int ulfius_add_endpoint or int ulfius_add_endpoint_by_val. It's recommended to use the dedicated functions to fill this array though.

If you manipulate the attribute u_instance.endpoint_list, you must end the list with an empty endpoint (see Constants Structures _u_endpoint * ulfius_empty_endpoint()), and you must set the attribute u_instance.nb_endpoints accordingly. Also, you must use dynamically allocated values (malloc) for attributes http_method, url_prefix and url_format.

## Multiple callback functions

Ulfius allows multiple callbacks for the same endpoint. This is helpful when you need to execute several actions in sequence, for example check authentication, get resource, set cookie, then gzip response body. That's also why a priority must be set for each callback.

The priority is in descending order, which means that it starts with 0 (highest priority) and priority decreases when priority number increases. There is no more signification to the priority number, which means you can use any increments of your choice.

Warning: Having 2 callback functions with the same priority number will result in an undefined execution order result.

To help passing parameters between callback functions of the same request, the value Structures _u_response.shared_data can be used. It's recommended to use the function ulfius_set_response_shared_data with a pointer to a free function for shared_data, therefore the framework will automatically clean Structures _u_response.shared_data at the end of the callback list.

## Multiple URLs with similar pattern

If you need to differentiate multiple URLs with similar pattern, you can use priorities among multiple callback function.

For example, if you have 2 endpoints with the following patterns:

1- /example/:id 2- /example/findByStatus

You'll probably need the callback referred in 2- to be called and the callback referred in 1- not when the URL called is the exact pattern as in 2-. Nevertheless, you'll need callback referred in 1- in all the other cases.

In that case, you'll have to set a higher priority to the endpoint with the URL 2- and return its callback function with the value U_CALLBACK_COMPLETE. Remember, if the first callback returns U_CALLBACK_CONTINUE, the second callback will be called afterwards.

int callback_example_find_by_status(const struct _u_request * request, struct _u_response * response, void * user_data) {
/* do something here... */
return U_CALLBACK_COMPLETE;
}
int callback_example_by_id(const struct _u_request * request, struct _u_response * response, void * user_data) {
/* do something else there... */
return U_CALLBACK_CONTINUE;
}
int main() {
/* initialize program and instance */
ulfius_add_endpoint_by_val(instance, "GET", NULL, "/example/:id", 1, &callback_example_by_id, my_user_data);
ulfius_add_endpoint_by_val(instance, "GET", NULL, "/example/findByStatus", 0, &callback_example_find_by_status, my_user_data);
/* start instance and run program */
}
U_CALLBACK_COMPLETE
#define U_CALLBACK_COMPLETE
Callback exited with success, exit callback list.
Definition ulfius.h:121
U_CALLBACK_CONTINUE
#define U_CALLBACK_CONTINUE
Callback exited with success, continue to next callback.
Definition ulfius.h:119

# Start and stop webservice

## 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:

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
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
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
int ulfius_start_framework(struct _u_instance *u_instance)
Definition ulfius.c:1166
ulfius_start_secure_framework
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 struct _u_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.

## Stop webservice

To stop the webservice, call the following function:

int ulfius_stop_framework(struct _u_instance * u_instance);
ulfius_stop_framework
int ulfius_stop_framework(struct _u_instance *u_instance)
Definition ulfius.c:1301

# Callback functions management

The callback function is the function executed when a user calls an endpoint managed by your webservice (as defined in your Structures _u_endpoint list).

The callback function has the following signature:

int (* callback_function)(const struct _u_request * request, // Input parameters (set by the framework)
struct _u_response * response, // Output parameters (set by the user)
void * user_data);

In the callback function definition, the variables request and response will be initialized by the framework, and the user_data variable will be assigned to the user_data defined in your endpoint list definition.

## Request structure

The request variable is defined as:

struct _u_request {
char * http_protocol;
char * http_verb;
char * http_url;
char * url_path;
char * proxy;
#if MHD_VERSION >= 0x00095208
unsigned short network_type;
#endif
int check_server_certificate;
int check_server_certificate_flag;
int check_proxy_certificate;
int check_proxy_certificate_flag;
int follow_redirect;
char * ca_path;
unsigned long timeout;
struct sockaddr * client_address;
char * auth_basic_user;
char * auth_basic_password;
struct _u_map * map_url;
struct _u_map * map_header;
struct _u_map * map_cookie;
struct _u_map * map_post_body;
void * binary_body;
size_t binary_body_length;
unsigned int callback_position;
#ifndef U_DISABLE_GNUTLS
gnutls_x509_crt_t client_cert;
char * client_cert_file;
char * client_key_file;
char * client_key_password;
#endif
};
_u_request::timeout
unsigned long timeout
Definition ulfius.h:248
_u_request::check_server_certificate_flag
int check_server_certificate_flag
Definition ulfius.h:243
_u_request::follow_redirect
int follow_redirect
Definition ulfius.h:246
_u_request::auth_basic_password
char * auth_basic_password
Definition ulfius.h:251
_u_request::http_protocol
char * http_protocol
Definition ulfius.h:234
_u_request::check_proxy_certificate_flag
int check_proxy_certificate_flag
Definition ulfius.h:245
_u_request::client_key_password
char * client_key_password
Definition ulfius.h:263
_u_request::binary_body
void * binary_body
Definition ulfius.h:256
_u_request::client_cert
gnutls_x509_crt_t client_cert
Definition ulfius.h:260
_u_request::map_cookie
struct _u_map * map_cookie
Definition ulfius.h:254
_u_request::binary_body_length
size_t binary_body_length
Definition ulfius.h:257
_u_request::map_header
struct _u_map * map_header
Definition ulfius.h:253
_u_request::check_server_certificate
int check_server_certificate
Definition ulfius.h:242
_u_request::client_address
struct sockaddr * client_address
Definition ulfius.h:249
_u_request::ca_path
char * ca_path
Definition ulfius.h:247
_u_request::map_post_body
struct _u_map * map_post_body
Definition ulfius.h:255
_u_request::check_proxy_certificate
int check_proxy_certificate
Definition ulfius.h:244
_u_request::client_key_file
char * client_key_file
Definition ulfius.h:262
_u_request::url_path
char * url_path
Definition ulfius.h:237
_u_request::auth_basic_user
char * auth_basic_user
Definition ulfius.h:250
_u_request::http_verb
char * http_verb
Definition ulfius.h:235
_u_request::callback_position
unsigned int callback_position
Definition ulfius.h:258
_u_request::proxy
char * proxy
Definition ulfius.h:238
_u_request::http_url
char * http_url
Definition ulfius.h:236
_u_request::map_url
struct _u_map * map_url
Definition ulfius.h:252
_u_request::client_cert_file
char * client_cert_file
Definition ulfius.h:261

Functions dedicated to handle the request:

int ulfius_set_string_body_request(struct _u_response * request, const char * string_body);
int ulfius_set_binary_body_request(struct _u_response * request, const char * binary_body, const size_t length);
int ulfius_set_empty_body_request(struct _u_request * request);
ulfius_set_empty_body_request
int ulfius_set_empty_body_request(struct _u_request *request)
Definition u_request.c:751
ulfius_set_string_body_request
int ulfius_set_string_body_request(struct _u_request *request, const char *string_body)
Definition u_request.c:704
ulfius_set_binary_body_request
int ulfius_set_binary_body_request(struct _u_request *request, const char *binary_body, const size_t length)
Definition u_request.c:726

## ulfius_set_request_properties

The function ulfius_set_request_properties allows to put a variable set of request properties in a single-line. The parameter list MUST end with the option U_OPT_NONE

/**
* ulfius_set_request_properties
* Set a list of properties to a request
* return U_OK on success
*/
int ulfius_set_request_properties(struct _u_request * request, ...);

Options available:

Option | Description
--- | ---
U_OPT_NONE | Empty option to complete a ulfius_set_request_properties or ulfius_set_request_properties
U_OPT_HTTP_VERB | http method (GET, POST, PUT, DELETE, etc.), expected option value type: const char *
U_OPT_HTTP_URL | full URL used to call this callback function or full URL to call when used in a ulfius_send_http_request, expected option value type: const char *
U_OPT_HTTP_URL_APPEND | append char * value to the current url, expected option value type: const char *
U_OPT_HTTP_PROXY | proxy address to use for outgoing connections, used by ulfius_send_http_request, expected option value type: const char *
U_OPT_NETWORK_TYPE | Force connect to IPv4, IPv6 addresses or both, values available are U_USE_ALL, U_USE_IPV4 or U_USE_IPV6, expected option value type: unsigned short
U_OPT_CHECK_SERVER_CERTIFICATE | check server certificate and hostname, default true, used by ulfius_send_http_request, expected option value type: int
U_OPT_CHECK_SERVER_CERTIFICATE_FLAG | check certificate peer and or server hostname if check_server_certificate is enabled, values available are U_SSL_VERIFY_PEER, U_SSL_VERIFY_HOSTNAME or both, default value is both (U_SSL_VERIFY_PEER|U_SSL_VERIFY_HOSTNAME), used by ulfius_send_http_request, expected option value type: int
U_OPT_CHECK_PROXY_CERTIFICATE | check proxy certificate and hostname, default true, used by ulfius_send_http_request, requires libcurl >= 7.52, expected option value type: int
U_OPT_CHECK_PROXY_CERTIFICATE_FLAG | check certificate peer and or proxy hostname if check_proxy_certificate is enabled, values available are U_SSL_VERIFY_PEER, U_SSL_VERIFY_HOSTNAME or both, default value is both (U_SSL_VERIFY_PEER|U_SSL_VERIFY_HOSTNAME), used by ulfius_send_http_request, requires libcurl >= 7.52, expected option value type: int
U_OPT_FOLLOW_REDIRECT | follow URL redirections, used by ulfius_send_http_request, expected option value type: int
U_OPT_CA_PATH | specify a path to CA certificates instead of system path, used by ulfius_send_http_request, expected option value type: const char *
U_OPT_TIMEOUT | connection timeout used by ulfius_send_http_request, default is 0 or Timeout in seconds to close the connection because of inactivity between the client and the server, expected option value type: unsigned long
U_OPT_AUTH_BASIC_USER | basic authentication username, expected option value type: const char *
U_OPT_AUTH_BASIC_PASSWORD | basic authentication password, expected option value type: const char *
U_OPT_URL_PARAMETER | Add to the map containing the URL variables, both from the route and the ?key=value variables, expected option value type: const char *, const char *
U_OPT_HEADER_PARAMETER | Add to the map containing the header variables, expected option value type: const char *, const char *
U_OPT_COOKIE_PARAMETER | Add to the map containing the cookie variables, expected option value type: const char *, const char *
U_OPT_POST_BODY_PARAMETER | Add to the map containing the post body variables (if available), expected option value type: const char *, const char *
U_OPT_URL_PARAMETER_REMOVE | Remove from the map containing the URL variables, both from the route and the ?key=value variables, expected option value type: const char *
U_OPT_HEADER_PARAMETER_REMOVE | Remove from map containing the header variables, expected option value type: const char *
U_OPT_COOKIE_PARAMETER_REMOVE | Remove from map containing the cookie variables, expected option value type: const char *
U_OPT_POST_BODY_PARAMETER_REMOVE | Remove from map containing the post body variables (if available), expected option value type: const char *
U_OPT_BINARY_BODY | Set a raw body to the request or the response, expected option value type: const char *, size_t
U_OPT_STRING_BODY | Set a char * body to the request or the response, expected option value type: const char *
U_OPT_JSON_BODY | Set a stringified json_t * body to the request or the response, expected option value type: json_t *
U_OPT_CLIENT_CERT_FILE | path to client certificate file for sending http requests with certificate authentication, available only if GnuTLS support is enabled, expected option value type: const char *
U_OPT_CLIENT_KEY_FILE | path to client key file for sending http requests with certificate authentication, available only if GnuTLS support is enabled, expected option value type: const char *
U_OPT_CLIENT_KEY_PASSWORD | password to unlock client key file, available only if GnuTLS support is enabled, expected option value type: const char *

Example:

ulfius_set_request_properties(&req, U_OPT_HTTP_VERB, "POST", U_OPT_HTTP_URL, "https://www.example.com/", U_OPT_CHECK_SERVER_CERTIFICATE, 0, U_OPT_STRING_BODY, "Hello World!", U_OPT_HEADER_PARAMETER, "Content-Type", "PlainText", U_OPT_NONE);
U_OPT_HTTP_URL
@ U_OPT_HTTP_URL
full url used to call this callback function or full url to call when used in a ulfius_send_http_requ...
Definition ulfius.h:148
U_OPT_HTTP_VERB
@ U_OPT_HTTP_VERB
http method (GET, POST, PUT, DELETE, etc.), expected option value type: const char *
Definition ulfius.h:147
U_OPT_NONE
@ U_OPT_NONE
Empty option to complete a ulfius_set_request_properties or ulfius_set_request_properties.
Definition ulfius.h:146
U_OPT_CHECK_SERVER_CERTIFICATE
@ U_OPT_CHECK_SERVER_CERTIFICATE
check server certificate and hostname, default true, used by ulfius_send_http_request,...
Definition ulfius.h:153
U_OPT_STRING_BODY
@ U_OPT_STRING_BODY
Set a char * body to the request or the reponse, expected option value type: const char *.
Definition ulfius.h:172
U_OPT_HEADER_PARAMETER
@ U_OPT_HEADER_PARAMETER
Add to the map containing the header variables, expected option value type: const char *,...
Definition ulfius.h:164
ulfius_set_request_properties
int ulfius_set_request_properties(struct _u_request *request,...)
Definition u_request.c:494

## Response structure

The response variable is defined as:

struct _u_response {
long status;
char * protocol;
struct _u_map * map_header;
unsigned int nb_cookies;
struct _u_cookie * map_cookie;
char * auth_realm;
void * binary_body;
size_t binary_body_length;
ssize_t (* stream_callback) (void * stream_user_data, uint64_t offset, char * out_buf, size_t max);
void (* stream_callback_free) (void * stream_user_data);
uint64_t stream_size;
size_t stream_block_size;
void * stream_user_data;
void * websocket_handle;
void * shared_data;
void (* free_shared_data)(void * shared_data);
unsigned int timeout;
};
_u_cookie
Definition ulfius.h:215
_u_response::protocol
char * protocol
Definition ulfius.h:275
_u_response::stream_block_size
size_t stream_block_size
Definition ulfius.h:285
_u_response::stream_user_data
void * stream_user_data
Definition ulfius.h:286
_u_response::stream_callback
ssize_t(* stream_callback)(void *stream_user_data, uint64_t offset, char *out_buf, size_t max)
Definition ulfius.h:282
_u_response::websocket_handle
void * websocket_handle
Definition ulfius.h:287
_u_response::stream_size
uint64_t stream_size
Definition ulfius.h:284
_u_response::binary_body_length
size_t binary_body_length
Definition ulfius.h:281
_u_response::map_header
struct _u_map * map_header
Definition ulfius.h:276
_u_response::status
long status
Definition ulfius.h:274
_u_response::nb_cookies
unsigned int nb_cookies
Definition ulfius.h:277
_u_response::timeout
unsigned int timeout
Definition ulfius.h:290
_u_response::map_cookie
struct _u_cookie * map_cookie
Definition ulfius.h:278
_u_response::auth_realm
char * auth_realm
Definition ulfius.h:279
_u_response::stream_callback_free
void(* stream_callback_free)(void *stream_user_data)
Definition ulfius.h:283
_u_response::free_shared_data
void(* free_shared_data)(void *shared_data)
Definition ulfius.h:289
_u_response::binary_body
void * binary_body
Definition ulfius.h:280
_u_response::shared_data
void * shared_data
Definition ulfius.h:288

In the response variable set by the framework to the callback function, the structure is initialized with no data.

The user can set the binary_body before the return statement, or no response body at all if no need. If a binary_body is set, its size must be set to binary_body_length. binary_body is freed by the framework when the response has been sent to the client, so you must use dynamically allocated values. If no status is set, status 200 will be sent to the client.

Some functions are dedicated to handle the response:

int ulfius_add_header_to_response(struct _u_response * response, const char * key, const char * value);
int ulfius_set_string_body_response(struct _u_response * response, const unsigned int status, const char * body);
int ulfius_set_binary_response(struct _u_response * response, const unsigned int status, const char * body, const size_t length);
int ulfius_set_empty_body_response(struct _u_response * response, const unsigned int status);
int ulfius_set_stream_response(struct _u_response * response,
const unsigned int status,
ssize_t (* stream_callback) (void * stream_user_data, uint64_t offset, char * out_buf, size_t max);
void (* stream_callback_free) (void * stream_user_data),
uint64_t stream_size,
size_t stream_block_size,
void * stream_user_data);
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);
ulfius_add_header_to_response
int ulfius_add_header_to_response(struct _u_response *response, const char *key, const char *value)
Definition u_response.c:717
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
ulfius_set_empty_body_response
int ulfius_set_empty_body_response(struct _u_response *response, const unsigned int status)
Definition u_response.c:555
ulfius_set_stream_response
int ulfius_set_stream_response(struct _u_response *response, const unsigned int status, ssize_t(*stream_callback)(void *stream_user_data, uint64_t offset, char *out_buf, size_t max), void(*stream_callback_free)(void *stream_user_data), uint64_t stream_size, size_t stream_block_size, void *stream_user_data)
Definition u_response.c:569
_u_cookie::key
char * key
Definition ulfius.h:216
_u_cookie::value
char * value
Definition ulfius.h:217
ulfius_set_websocket_response
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)
Definition u_websocket.c:1834

## ulfius_set_response_properties

The function ulfius_set_response_properties allows to put a variable set of response properties in a single-line. The parameter list MUST end with the option U_OPT_NONE

int ulfius_set_response_properties(struct _u_response * response, ...);
ulfius_set_response_properties
int ulfius_set_response_properties(struct _u_response *response,...)
Definition u_response.c:594

Options available:

Option | Description
--- | ---
U_OPT_NONE | Empty option to complete a ulfius_set_request_properties or ulfius_set_request_properties
U_OPT_STATUS | HTTP response status code (200, 404, 500, etc), expected option value type: long
U_OPT_AUTH_REALM | realm to send to the client response on authentication failed, expected option value type: const char *
U_OPT_SHARED_DATA | any data shared between callback functions, must be allocated and freed by the callback functions, expected option value type: void *
U_OPT_TIMEOUT | Timeout in seconds to close the connection because of inactivity between the client and the server, expected option value type: long
U_OPT_HEADER_PARAMETER | Add to the map containing the header variables, expected option value type: const char *, const char *
U_OPT_HEADER_PARAMETER_REMOVE | Remove from map containing the header variables, expected option value type: const char *
U_OPT_BINARY_BODY | Set a raw body to the request or the response, expected option value type: const char *, size_t
U_OPT_STRING_BODY | Set a char * body to the request or the response, expected option value type: const char *
U_OPT_JSON_BODY | Set a stringified json_t * body to the request or the response, expected option value type: json_t *

Example:

ulfius_set_response_properties(&req, U_OPT_STATUS, 200, U_OPT_STRING_BODY, "Hello World!", U_OPT_HEADER_PARAMETER, "Content-Type", "PlainText", U_OPT_NONE);
U_OPT_STATUS
@ U_OPT_STATUS
HTTP response status code (200, 404, 500, etc), expected option value type: long.
Definition ulfius.h:181

## Callback functions return value

The callback returned value can have the following values:

- U_CALLBACK_CONTINUE: The framework can transfer the request and the response to the next callback function in priority order if there is one, or complete the transaction and send back the response to the client.
- U_CALLBACK_IGNORE: The framework can transfer the request and the response to the next callback function in priority order if there is one, or complete the transaction and send back the response to the client, the counter request->callback_position will not be incremented. If at the end of the callback list request->callback_position is 0, the default callback (if set) will be called.
- U_CALLBACK_COMPLETE: The framework must complete the transaction and send the response to the client without calling any further callback function.
- U_CALLBACK_UNAUTHORIZED: The framework must complete the transaction without calling any further callback function and send an unauthorized response to the client with the status 401, the body specified and the auth_realm value if specified.
- U_CALLBACK_ERROR: An error occurred during execution, the framework will complete the transaction without calling any further callback function and send an error 500 to the client.

Except for the return values U_CALLBACK_UNAUTHORIZED and U_CALLBACK_ERROR, the callback return value isn't useful to specify the response sent back to the client. Use the Structures _u_response variable in your callback function to set all values in the HTTP response.

## Use JSON in request and response body

In Ulfius 2.0, hard dependency with libjansson has been removed, the Jansson library is now optional but enabled by default.

If you want to remove JSON dependency, build Ulfius library using Makefile with the flag JANSSONFLAG=1 or CMake with the option -DWITH_WEBSOCKET=off.

$ make JANSSONFLAG=1 # Makefile
$ cmake -DWITH_WEBSOCKET=off # CMake

if JSON is enabled, the following functions are available in Ulfius:

json_t * ulfius_get_json_body_request(const struct _u_request * request, json_error_t * json_error);
int ulfius_set_json_body_request(struct _u_request * request, json_t * body);
json_t * ulfius_get_json_body_response(struct _u_response * response, json_error_t * json_error);
int ulfius_set_json_body_response(struct _u_response * response, const unsigned int status, const json_t * body);
ulfius_get_json_body_response
json_t * ulfius_get_json_body_response(struct _u_response *response, json_error_t *json_error)
Definition u_response.c:709
ulfius_get_json_body_request
json_t * ulfius_get_json_body_request(const struct _u_request *request, json_error_t *json_error)
Definition u_request.c:979
ulfius_set_json_body_response
int ulfius_set_json_body_response(struct _u_response *response, const unsigned int status, const json_t *j_body)
Definition u_response.c:682
ulfius_set_json_body_request
int ulfius_set_json_body_request(struct _u_request *request, json_t *j_body)
Definition u_request.c:953

The jansson API documentation is available at the following address: Jansson documentation.

Note: According to the JSON RFC section 6, the MIME media type for JSON text is application/json. Thus, if there is no HTTP header specifying JSON content-type, the functions ulfius_get_json_body_request and ulfius_get_json_body_response will return NULL.

## Additional functions

In addition with manipulating the raw parameters of the structures, you can use the _u_request and _u_response structures by using specific functions designed to facilitate their use and memory management:

int ulfius_init_request(struct _u_request * request);
int ulfius_clean_request(struct _u_request * request);
int ulfius_clean_request_full(struct _u_request * request);
int ulfius_init_response(struct _u_response * response);
int ulfius_clean_response(struct _u_response * response);
int ulfius_clean_response_full(struct _u_response * response);
int ulfius_copy_response(struct _u_response * dest, const struct _u_response * source);
int ulfius_clean_cookie(struct _u_cookie * cookie);
int ulfius_copy_cookie(struct _u_cookie * dest, const struct _u_cookie * source);
struct _u_request * ulfius_duplicate_request(const struct _u_request * request);
struct _u_response * ulfius_duplicate_response(const struct _u_response * response);
ulfius_copy_cookie
int ulfius_copy_cookie(struct _u_cookie *dest, const struct _u_cookie *source)
Definition u_response.c:307
ulfius_init_request
int ulfius_init_request(struct _u_request *request)
Definition u_request.c:267
ulfius_init_response
int ulfius_init_response(struct _u_response *response)
Definition u_response.c:373
ulfius_copy_response
int ulfius_copy_response(struct _u_response *dest, const struct _u_response *source)
Definition u_response.c:426
ulfius_clean_request_full
int ulfius_clean_request_full(struct _u_request *request)
Definition u_request.c:366
ulfius_duplicate_response
struct _u_response * ulfius_duplicate_response(const struct _u_response *response)
Definition u_response.c:493
ulfius_duplicate_request
struct _u_request * ulfius_duplicate_request(const struct _u_request *request)
Definition u_request.c:767
ulfius_clean_cookie
int ulfius_clean_cookie(struct _u_cookie *cookie)
Definition u_response.c:289
ulfius_clean_response_full
int ulfius_clean_response_full(struct _u_response *response)
Definition u_response.c:364

## Memory management

The Ulfius framework will automatically free the variables referenced by the request and responses structures, so you must use dynamically allocated values for the response pointers.

## Character encoding

You may be careful with characters encoding if you use non UTF8 characters in your application or webservice source code, and especially if you use different encoding in the same application. Ulfius may not work properly.

## Accessing POST parameters

In the callback function, you can access the POST parameters in the Structures _u_request.map_post_body. The parameters keys are case-sensitive.

This variable is a Structures _u_map, therefore you can access it using the struct _u_map documentation.

// Example of accessing a POST parameter
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;
}
u_map_get
const char * u_map_get(const struct _u_map *u_map, const char *key)
Definition u_map.c:377

## Accessing query string and URL parameters

In the callback function, you can access the URL and query parameters in the Structures _u_request.map_url. This variable contains both URL parameters and query string parameters, the parameters keys are case-sensitive. If a parameter appears multiple times in the URL and the query string, the values will be chained in the Structures _u_request.map_url, separated by a comma ,.

This variable is a Structures _u_map, therefore you can access it using the struct _u_map documentation.

// Example of accessing URL parameters
int callback_test (const struct _u_request * request, struct _u_response * response, void * user_data) {
printf("URL parameter id: %s\n", u_map_get(request->map_url, "id"));
return U_CALLBACK_CONTINUE;
}

## Accessing header parameters

In the callback function, you can access the header parameters in the Structures _u_request.map_header.

In the callback function, you can access the header parameters in the Structures _u_request.map_header. The parameters keys are case-sensitive. If a parameter appears multiple times in the header, the values will be chained in the Structures _u_request.map_header, separated by a comma ,.

This variable is a Structures _u_map, therefore you can access it using the struct _u_map documentation.

// Example of accessing a POST parameter
int callback_test (const struct _u_request * request, struct _u_response * response, void * user_data) {
printf("Heder parameter id: %s\n", u_map_get(request->map_header, "id"));
return U_CALLBACK_CONTINUE;
}

## Cookie management

The map_cookie structure will contain a set of key/values for the cookies. The cookie structure is defined as

struct _u_cookie {
char * key;
char * value;
char * expires;
unsigned int max_age;
char * domain;
char * path;
int secure;
int http_only;
int same_site;
};
_u_cookie::path
char * path
Definition ulfius.h:221
_u_cookie::expires
char * expires
Definition ulfius.h:218
_u_cookie::domain
char * domain
Definition ulfius.h:220
_u_cookie::http_only
int http_only
Definition ulfius.h:223
_u_cookie::secure
int secure
Definition ulfius.h:222
_u_cookie::same_site
int same_site
Definition ulfius.h:224
_u_cookie::max_age
unsigned int max_age
Definition ulfius.h:219

You can use the functions ulfius_add_cookie_to_response or ulfius_add_same_site_cookie_to_response in your callback function to facilitate cookies management. These functions are defined as:

int ulfius_add_cookie_to_response(struct _u_response * response, const char * key, const char * value, const char * expires, const unsigned int max_age,
const char * domain, const char * path, const int secure, const int http_only);
int ulfius_add_same_site_cookie_to_response(struct _u_response * response, const char * key, const char * value, const char * expires, const unsigned int max_age,
const char * domain, const char * path, const int secure, const int http_only, const int same_site);
ulfius_add_cookie_to_response
int ulfius_add_cookie_to_response(struct _u_response *response, const char *key, const char *value, const char *expires, const unsigned int max_age, const char *domain, const char *path, const int secure, const int http_only)
Definition u_response.c:206
ulfius_add_same_site_cookie_to_response
int ulfius_add_same_site_cookie_to_response(struct _u_response *response, const char *key, const char *value, const char *expires, const unsigned int max_age, const char *domain, const char *path, const int secure, const int http_only, const int same_site)
Definition u_response.c:211

If you need to remove a cookie on the client, you can send a cookie with the same key but an empty value and a expiration in the past.

/*
* Example of a cookie removal, you must change the values domain, path, secure, http_only
* according to your settings
*/
char * expires = "Sat, 10 Jan 1970 12:00:00 GMT"
ulfius_add_cookie_to_response(response, "cookie_key", "", expires, 0, "your_domain.tld", "/", 0, 0);

Please note that the client (browser, app, etc.) doesn't have to remove the cookies if it doesn't want to.

# File upload

Ulfius allows file upload to the server. Beware that an uploaded file will be stored in the request object in memory, so uploading large files may dramatically slow the application or even crash it, depending on your system. An uploaded file is stored in the request->map_body structure. You can use u_map_get_length to get the exact length of the file as it may not be a string format.

If you want to limit the size of a post parameter, if you want to limit the file size for example, set the value Structures _u_instance.max_post_param_size. Files or post data exceeding this size will be truncated to the size Structures _u_instance.max_post_param_size. If this parameter is 0, then no limit is set. Default value is 0.

If you want to handle file upload yourself, you can intercept the file upload process with your own callback function. Before running the webservice with ulfius_start_framework, you must call the function ulfius_set_upload_file_callback_function with a pointer to your file upload callback function. By using this method, the specified callback function will be executed as much as needed with a chunk of the file upload each time.

This function ulfius_set_upload_file_callback_function has the following prototype:

int ulfius_set_upload_file_callback_function(struct _u_instance * u_instance,
int (* file_upload_callback) (const struct _u_request * request,
const char * key,
const char * filename,
const char * content_type,
const char * transfer_encoding,
const char * data,
uint64_t off,
size_t size,
void * cls),
void * cls);
ulfius_set_upload_file_callback_function
int ulfius_set_upload_file_callback_function(struct _u_instance *u_instance, int(*file_upload_callback)(const struct _u_request *request, const char *key, const char *filename, const char *content_type, const char *transfer_encoding, const char *data, uint64_t off, size_t size, void *cls), void *cls)
Definition ulfius.c:1604

This callback function will be called before all the other callback functions, and be aware that not all parameters, especially URL parameters, will be present during the file upload callback function executions.

See examples/sheep_counter for a file upload example.

## Binary file upload

By default, Ulfius will check input body data to be valid utf8 characters. This will most likely break binary files uploaded via multipart/form-data transfert-encoding.

If you don't or can't use ulfius_set_upload_file_callback_function, you must disable utf8 check before starting ulfius instance, then in the callback function, make sure to use u_map_get_length for every request->map_post_body element.

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;
}
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...
}
u_map_get_length
ssize_t u_map_get_length(const struct _u_map *u_map, const char *key)
Definition u_map.c:433

# Streaming data

If you need to stream data, i.e. send a variable and potentially large amount of data, or if you need to send a chunked response, you can define and use stream_callback_function in the Structures _u_response.

Not that if you stream data to the client, any data that was in the response->binary_body will be ignored. You must at least set the function pointer Structures _u_response.stream_callback to stream data. Set stream_size to U_STREAM_SIZE_UNKNOWN if you don't know the size of the data you need to send, like in audio stream for example. Set stream_block_size according to you system resources to avoid out of memory errors, also, set stream_callback_free with a pointer to a function that will free values allocated by your stream callback function, as a close() file for example, and finally, you can set stream_user_data to a pointer.

You can use the function ulfius_set_stream_response to set those parameters.

The prototype of the stream_callback function is the following:

ssize_t stream_callback (void * stream_user_data, // Your predefined user_data
uint64_t offset, // the position of the current data to send
char * out_buf, // The output buffer to fill with data
size_t max); // the max size of data to be put in the out_buf

The return value must be the size of the data put in out_buf.

This function will be called over and over in loop as long as the client has the connection opened.

If you want to close the stream from the server side, return U_STREAM_END in the stream_callback function. If a problem occurred, you can close the connection with a U_STREAM_ERROR return value.

While the stream_callback_free function is as simple as:

void stream_callback_free (void * stream_user_data);

Check the application stream_example in the example folder.

# Websockets communication

The websocket protocol is defined in the RFC6455. A websocket is a full-duplex communication layer between a server and a client initiated by a HTTP request. Once the websocket handshake is complete between the client and the server, the TCP socket between them is kept open and messages in a specific format can be exchanged. Any side of the socket can send a message to the other side, which allows the server to push messages to the client.

Ulfius implements websocket communication, both server-side and client-side. The following chapter will describe how to create a websocket service or a websocket client by using callback functions. The framework will handle sending and receiving messages with the clients, and your application will deal with high level functions to facilitate the communication process.

## Websocket management

During the websocket connection, you can either send messages, read the incoming messages, close the connection, or wait until the connection is closed by the client or by a network problem.

## Messages manipulation

A websocket message has the following structure:

struct _websocket_message {
time_t datestamp; // datestamp when the message was transmitted
uint8_t rsv; // RSV (extension) flags, must be binary tested over U_WEBSOCKET_RSV1, U_WEBSOCKET_RSV2, U_WEBSOCKET_RSV3
uint8_t opcode; // opcode of the message: U_WEBSOCKET_OPCODE_TEXT, U_WEBSOCKET_OPCODE_BINARY, U_WEBSOCKET_OPCODE_PING, U_WEBSOCKET_OPCODE_PONG
uint8_t has_mask; // Flag to specify if the message has a mask
uint8_t mask[4]; // mask
size_t data_len; // Length of the data payload
char * data; // data payload
};

The different opcode values available are the following:

U_WEBSOCKET_OPCODE_TEXT
U_WEBSOCKET_OPCODE_BINARY
U_WEBSOCKET_OPCODE_CLOSE
U_WEBSOCKET_OPCODE_PING

To send a message to the client, use the dedicated functions ulfius_websocket_send_message, ulfius_websocket_send_fragmented_message or ulfius_websocket_send_json_message:

int ulfius_websocket_send_message(struct _websocket_manager * websocket_manager,
const uint8_t opcode,
const uint64_t data_len,
const char * data);
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);
int ulfius_websocket_send_json_message(struct _websocket_manager * websocket_manager,
json_t * j_message);
ulfius_websocket_send_json_message
int ulfius_websocket_send_json_message(struct _websocket_manager *websocket_manager, json_t *j_message)
Definition u_websocket.c:1594
ulfius_websocket_send_message
int ulfius_websocket_send_message(struct _websocket_manager *websocket_manager, const uint8_t opcode, const uint64_t data_len, const char *data)
Definition u_websocket.c:1582
ulfius_websocket_send_fragmented_message
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)
Definition u_websocket.c:1482

To get the first message of the incoming or outcoming if you need to with ulfius_websocket_pop_first_message, this will remove the first message of the list, and return it as a pointer. You must free the message using the function ulfius_clear_websocket_message after use:

All the sent or received messages are stored by default in the Structures _websocket_manager attributes message_list_incoming and message_list_outcoming. To skip storing incoming and/or outcoming messages, you can set the flag Structures _websocket_manager.keep_messages with the values U_WEBSOCKET_KEEP_INCOMING, U_WEBSOCKET_KEEP_OUTCOMING or U_WEBSOCKET_KEEP_NONE. The flag is set to default with U_WEBSOCKET_KEEP_INCOMING|U_WEBSOCKET_KEEP_OUTCOMING.

if you exchange messages in JSON format, you can use ulfius_websocket_parse_json_message to parse a Structures _websocket_message * payload into a json_t * object.

struct _websocket_message * ulfius_websocket_pop_first_message(struct _websocket_message_list * message_list);
void ulfius_clear_websocket_message(struct _websocket_message * message);
json_t * ulfius_websocket_parse_json_message(const struct _websocket_message * message, json_error_t * json_error);
ulfius_websocket_parse_json_message
json_t * ulfius_websocket_parse_json_message(const struct _websocket_message *message, json_error_t *json_error)
Definition u_websocket.c:1614
ulfius_websocket_pop_first_message
struct _websocket_message * ulfius_websocket_pop_first_message(struct _websocket_message_list *message_list)
Definition u_websocket.c:1629
ulfius_clear_websocket_message
void ulfius_clear_websocket_message(struct _websocket_message *message)
Definition u_websocket.c:1652

### Fragmented messages limitation in browsers

It seems that some browsers like Firefox or Chromium don't like to receive fragmented messages, they will close the connection with a fragmented message is received. Use ulfius_websocket_send_fragmented_message with caution then.

## Server-side websocket

### Open a websocket communication

To start a websocket communication between the client and your application, you must use the dedicated function ulfius_start_websocket_cb with proper values:

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);

According to the Websockets RFC, parameters websocket_protocol and websocket_extensions are specific for your application.

In Ulfius Implementation, if you specify a list of protocols as a string of protocol names, separated by a comma (,), Ulfius framework will check each one and see if they match the list of protocols specified by the client. The resulting protocol list will be sent back to the client. Likewise, the websocket extension is specific to your application, you can specify a list of websocket extension separated by a comma (,).

If no protocol match your list, the connection will be closed by the framework and will return an error 400 to the client. If you set a NULL value for the protocol and/or the extension, Ulfius will not accept any protocols and/or extension sent by the client, but the websocket connexion will be opened.

3 callback functions are available for the websocket implementation:

- websocket_manager_callback: This function will be called in a separate thread, and the websocket will remain open as long as this callback function is not completed. In this function, your program will have access to the websocket status (connected or not), and the list of messages sent and received. When this function ends, the websocket will close itself automatically.
- websocket_incoming_message_callback: This function will be called every time a new message is sent by the client. Although, it is in synchronous mode, which means that you won't have 2 different websocket_incoming_message_callback of the same websocket executed at the same time.
- websocket_onclose_callback: This optional function will be called right after the websocket connection is closed, but before the websocket structure is cleaned.

You must specify at least one of the callback functions between websocket_manager_callback or websocket_incoming_message_callback.

When the function ulfius_stop_framework is called, it will wait for all running websockets to end by themselves, there is no force close. So if you have a websocket_manager_callback function running, you MUST end this function in order to make a clean stop of the http daemon.

For each of these callback function, you can specify a *_user_data pointer containing any data you need.

### Advanced websocket extension

Since Ulfius 2.7.0, you have advanced functions to handle websocket extensions based on the functions ulfius_add_websocket_extension_message_perform for the server websockets and ulfius_add_websocket_client_extension_message_perform for the clients websockets.

int ulfius_add_websocket_extension_message_perform(struct _u_response * response,
const char * extension_server,
int (* websocket_extension_message_out_perform)(const uint8_t opcode,
uint8_t * rsv,
const uint64_t data_len_in,
const char * data_in,
uint64_t * data_len_out,
char ** data_out,
const uint64_t fragment_len,
void * user_data,
void * context),
void * websocket_extension_message_out_perform_user_data,
int (* websocket_extension_message_in_perform)(const uint8_t opcode,
uint8_t rsv,
const uint64_t data_len_in,
const char * data_in,
uint64_t * data_len_out,
char ** data_out,
const uint64_t fragment_len,
void * user_data,
void * context),
void * websocket_extension_message_in_perform_user_data,
int (* websocket_extension_server_match)(const char * extension_client,
const char ** extension_client_list,
char ** extension_server,
void * user_data,
void ** context),
void * websocket_extension_server_match_user_data,
void (* websocket_extension_free_context)(void * user_data,
void * context),
void * websocket_extension_free_context_user_data);
int ulfius_add_websocket_client_extension_message_perform(struct _websocket_client_handler * websocket_client_handler,
const char * extension,
int (* websocket_extension_message_out_perform)(const uint8_t opcode,
uint8_t * rsv,
const uint64_t data_len_in,
const char * data_in,
uint64_t * data_len_out,
char ** data_out,
const uint64_t fragment_len,
void * user_data,
void * context),
void * websocket_extension_message_out_perform_user_data,
int (* websocket_extension_message_in_perform)(const uint8_t opcode,
uint8_t rsv,
const uint64_t data_len_in,
const char * data_in,
uint64_t * data_len_out,
char ** data_out,
const uint64_t fragment_len,
void * user_data,
void * context),
void * websocket_extension_message_in_perform_user_data,
int (* websocket_extension_client_match)(const char * extension_server,
void * user_data,
void ** context),
void * websocket_extension_client_match_user_data,
void (* websocket_extension_free_context)(void * user_data,
void * context),
void * websocket_extension_free_context_user_data);
ulfius_add_websocket_extension_message_perform
int ulfius_add_websocket_extension_message_perform(struct _u_response *response, const char *extension_server, uint8_t rsv, int(*websocket_extension_message_out_perform)(const uint8_t opcode, const uint64_t data_len_in, const char *data_in, uint64_t *data_len_out, char **data_out, const uint64_t fragment_len, void *user_data, void *context), void *websocket_extension_message_out_perform_user_data, int(*websocket_extension_message_in_perform)(const uint8_t opcode, const uint64_t data_len_in, const char *data_in, uint64_t *data_len_out, char **data_out, const uint64_t fragment_len, void *user_data, void *context), void *websocket_extension_message_in_perform_user_data, int(*websocket_extension_server_match)(const char *extension_client, const char **extension_client_list, char **extension_server, void *user_data, void **context), void *websocket_extension_server_match_user_data, void(*websocket_extension_free_context)(void *user_data, void *context), void *websocket_extension_free_context_user_data)
Definition u_websocket.c:1881
ulfius_add_websocket_client_extension_message_perform
int ulfius_add_websocket_client_extension_message_perform(struct _websocket_client_handler *websocket_client_handler, const char *extension, uint8_t rsv, int(*websocket_extension_message_out_perform)(const uint8_t opcode, const uint64_t data_len_in, const char *data_in, uint64_t *data_len_out, char **data_out, const uint64_t fragment_len, void *user_data, void *context), void *websocket_extension_message_out_perform_user_data, int(*websocket_extension_message_in_perform)(const uint8_t opcode, const uint64_t data_len_in, const char *data_in, uint64_t *data_len_out, char **data_out, const uint64_t fragment_len, void *user_data, void *context), void *websocket_extension_message_in_perform_user_data, int(*websocket_extension_client_match)(const char *extension_server, void *user_data, void **context), void *websocket_extension_client_match_user_data, void(*websocket_extension_free_context)(void *user_data, void *context), void *websocket_extension_free_context_user_data)
Definition u_websocket.c:2438

These functions add the possibility to run a callback function before a message is sent and/or after a message is received.

The callback functions websocket_extension_server_match and websocket_extension_client_match can be use if you expect to match an extension with parameters. If NULL, then instead an exact match between Constants char * extension and the extension received will be checked to enable or not this extension callback functions.

int websocket_extension_server_match(const char * extension_client,
const char ** extension_client_list,
char ** extension_server,
void * user_data,
void ** context);
int websocket_extension_client_match(const char * extension_server, void * user_data, void ** context);

The callback function websocket_extension_message_out_perform can modify the message data and data lenght and the RSV flags. The callback function websocket_extension_message_in_perform can modify the message data only. Inside these functions, data_in and data_len_in are the current data, your extension callback function must update data_out with a o_malloc'ed data and set the new data length using data_len_out and return U_OK on success. If your function doesn't return U_OK, the message data won't be updated and data_out won't be free'd if set.

You can call ulfius_add_websocket_extension_message_perform or ulfius_add_websocket_client_extension_message_perform multiple times for a websocket definition. In that case the extension callbacks function will be called in the same order for the websocket_extension_message_out_perform callbacks, and in reverse order for the websocket_extension_message_in_perform callbacks.

### Built-in server extension permessage-deflate

The Websocket extension permessage-deflate used to compress the message data is available in Ulfius. To use this extension in your websocket server, you must call ulfius_add_websocket_deflate_extension after calling ulfius_set_websocket_response and before finishing the callback endpoint.

int ulfius_add_websocket_deflate_extension(struct _u_response * response);
ulfius_add_websocket_deflate_extension
int ulfius_add_websocket_deflate_extension(struct _u_response *response)
Definition u_websocket.c:2266

See the sample code in websocket_example/websocket_server.c

### Close a websocket communication

To close a websocket communication from the server, you can do one of the following:

- End the function websocket_manager_callback, it will result in closing the websocket connection
- Send a message with the opcode U_WEBSOCKET_OPCODE_CLOSE
- Call the function ulfius_websocket_wait_close or ulfius_websocket_send_close_signal described below

If no websocket_manager_callback is specified, you can send a U_WEBSOCKET_OPCODE_CLOSE in the websocket_incoming_message_callback function when you need, or call the function ulfius_websocket_send_close_signal.

If a callback function websocket_onclose_callback has been specified, this function will be executed on every case at the end of the websocket connection.

If the websocket handshake hasn't been correctly completed or if an error appears during the handshake connection, the callback websocket_onclose_callback will be called anyway, even if the callback functions websocket_manager_callback or websocket_incoming_message_callback are skipped due to no websocket connection. This is to allow the calling program to close opened resources or clean allocated memory. Beware that in this specific case, the parameter Structures _websocket_manager * websocket_manager may be NULL.

### Websocket status

The following functions allow the application to know if the the websocket is still open, to enforce closing the websocket or to wait until the websocket is closed by the client:

int ulfius_websocket_send_close_signal(struct _websocket_manager * websocket_manager);
int ulfius_websocket_status(struct _websocket_manager * websocket_manager);
int ulfius_websocket_wait_close(struct _websocket_manager * websocket_manager, unsigned int timeout);
ulfius_websocket_send_close_signal
int ulfius_websocket_send_close_signal(struct _websocket_manager *websocket_manager)
Definition u_websocket.c:2278
ulfius_websocket_wait_close
int ulfius_websocket_wait_close(struct _websocket_manager *websocket_manager, unsigned int timeout)
Definition u_websocket.c:2307
ulfius_websocket_status
int ulfius_websocket_status(struct _websocket_manager *websocket_manager)
Definition u_websocket.c:2293

## Client-side websocket

Ulfius allows to create a websocket connection as a client. The behavior is quite similar to the server-side websocket. The application will open a websocket connection specified by a Structures _u_request, and a set of callback functions to manage the websocket once connected.

### Prepare the request

You can manually fill the Structures _u_request with your parameters or use the dedicated function ulfius_set_websocket_request:

int ulfius_set_websocket_request(struct _u_request * request,
const char * url,
const char * websocket_protocol,
const char * websocket_extensions);
ulfius_set_websocket_request
int ulfius_set_websocket_request(struct _u_request *request, const char *url, const char *websocket_protocol, const char *websocket_extensions)
Definition u_websocket.c:2396

The url specified must have one of the following form:

- http://<websocket_url>
- ws://<websocket_url>
- https://<websocket_url>
- wss://<websocket_url>

The websocket_protocol and websocket_extensions values are optional. To specify multiple protocol, you must separate them with the comma , character. To specify multiple extensions, you must separate them with the semicolon ; character.

You can also specify additional headers or cookies to the request.

Any body parameter or body raw value will be ignored, the header Content-Length will be set to 0.

The header User-Agent value will be Ulfius Websocket Client Framework, feel free to modify it afterwards if you need.

### Built-in client extension permessage-deflate

The Websocket extension permessage-deflate used to compress the message data is available in Ulfius. To use this extension in your websocket client, you must call ulfius_add_websocket_client_deflate_extension after calling ulfius_set_websocket_request and before calling ulfius_open_websocket_client_connection. Also, the parameter Structures _websocket_client_handler must be initialized to {NULL, NULL} before calling ulfius_set_websocket_request.

/**
* Adds the required extension message perform to implement message compression according to
* RFC 7692: Compression Extensions for WebSocket
* https://tools.ietf.org/html/rfc7692
* @param websocket_client_handler the handler of the websocket
* @return U_OK on success
*/
int ulfius_add_websocket_client_deflate_extension(struct _websocket_client_handler * websocket_client_handler);

See the sample code in websocket_example/websocket_client.c

### Opening the websocket connection

Once the request is completed, you can open the websocket connection with ulfius_open_websocket_client_connection:

int ulfius_open_websocket_client_connection(struct _u_request * request,
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,
struct _websocket_client_handler * websocket_client_handler);
ulfius_open_websocket_client_connection
int ulfius_open_websocket_client_connection(struct _u_request *request, 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, struct _websocket_client_handler *websocket_client_handler, struct _u_response *response)
Definition u_websocket.c:2524

If the websocket connection is established, U_OK will be returned and the websocket connection will be executed in a separate thread.

### Closing a websocket communication

To close a websocket communication, you can do one of the following:

- End the function websocket_manager_callback, it will result in closing the websocket connection
- Send a message with the opcode U_WEBSOCKET_OPCODE_CLOSE
- Call the function ulfius_websocket_wait_close described below, this function will return U_OK when the websocket is closed
- Call the function ulfius_websocket_client_connection_send_close_signal described below, this function is non-blocking, it will send a closing signal to the websocket and will return even if the websocket is still open. You can use ulfius_websocket_wait_close or ulfius_websocket_client_connection_status to check if the websocket is closed.

Note - broken pipe

In some cases, when the client websocket connection is secured via TLS. If the connection is already closed, or broken, a SIGPIPE signal can occur, leading to a program crash. To avoid this issue, you can handle SIGPIPE signals using sigaction.

The following code is a simple example where all SIGPIPE signals are simply ignored:

#include <signal.h>
sigaction(SIGPIPE, &(struct sigaction){SIG_IGN}, NULL);

Check the sigaction documentation for more details.

## Client Websocket status

The following functions allow the application to know if the the websocket is still open, to enforce closing the websocket or to wait until the websocket is closed by the server:

int ulfius_websocket_client_connection_send_close_signal(struct _websocket_client_handler * websocket_client_handler);
int ulfius_websocket_client_connection_close(struct _websocket_client_handler * websocket_client_handler);
int ulfius_websocket_client_connection_status(struct _websocket_client_handler * websocket_client_handler);
int ulfius_websocket_client_connection_wait_close(struct _websocket_client_handler * websocket_client_handler, unsigned int timeout);
ulfius_websocket_client_connection_send_close_signal
int ulfius_websocket_client_connection_send_close_signal(struct _websocket_client_handler *websocket_client_handler)
Definition u_websocket.c:2761
ulfius_websocket_client_connection_wait_close
int ulfius_websocket_client_connection_wait_close(struct _websocket_client_handler *websocket_client_handler, unsigned int timeout)
Definition u_websocket.c:2815
ulfius_websocket_client_connection_status
int ulfius_websocket_client_connection_status(struct _websocket_client_handler *websocket_client_handler)
Definition u_websocket.c:2801
ulfius_websocket_client_connection_close
int ulfius_websocket_client_connection_close(struct _websocket_client_handler *websocket_client_handler)
Definition u_websocket.c:2774

# Outgoing request functions

Ulfius allows output functions to send HTTP or SMTP requests. These functions use libcurl. You can disable these functions by appending the argument CURLFLAG=1 when you build the library with Makefile or by disabling the flag in CMake build:

$ make CURLFLAG=1 # Makefile
$ cmake -DWITH_CURL=off # CMake

## Send HTTP request API

The functions int ulfius_send_http_request(const struct _u_request * request, struct _u_response * response) and int ulfius_send_http_streaming_request(Constants Structures _u_request * request, Structures _u_response * response, size_t (* write_body_function)(void * contents, size_t size, size_t nmemb, void * user_data), void * write_body_data) are based on libcurl API.

They allow to send an HTTP request with the parameters specified by the _u_request structure. Use the parameter _u_request.http_url to specify the distant URL to call.

You can fill the maps in the _u_request structure with parameters, they will be used to build the request. Note that if you fill _u_request.map_post_body with parameters, the content-type application/x-www-form-urlencoded will be used to encode the data.

The response parameters is stored into the _u_response structure. If you specify NULL for the response structure, the http call will still be made but no response details will be returned. If you use ulfius_send_http_request, the response body will be stored in the parameter response->*body*.

If you use ulfius_send_http_streaming_request, the response body will be available in the write_body_function specified in the call. The ulfius_send_http_streaming_request can be used for streaming data or large response, or if you need to receive a checked response from the server.

Return value is U_OK on success.

This functions are defined as:

int ulfius_send_http_request(const struct _u_request * request, struct _u_response * response);
int ulfius_send_http_request_with_limit(const struct _u_request * request, struct _u_response * response, size_t response_body_limit, size_t max_header);
int ulfius_send_http_streaming_request(const struct _u_request * request,
struct _u_response * response,
size_t (* write_body_function)(void * contents, size_t size, size_t nmemb, void * user_data),
void * write_body_data);
int ulfius_send_http_streaming_request_max_header(const struct _u_request * request,
struct _u_response * response,
size_t (* write_body_function)(void * contents, size_t size, size_t nmemb, void * user_data),
void * write_body_data,
size_t max_header);
ulfius_send_http_streaming_request
int ulfius_send_http_streaming_request(const struct _u_request *request, struct _u_response *response, size_t(*write_body_function)(void *contents, size_t size, size_t nmemb, void *user_data), void *write_body_data)
Definition u_send_request.c:267
ulfius_send_http_request_with_limit
int ulfius_send_http_request_with_limit(const struct _u_request *request, struct _u_response *response, size_t response_body_limit, size_t max_header)
Definition u_send_request.c:230
ulfius_send_http_request
int ulfius_send_http_request(const struct _u_request *request, struct _u_response *response)
Definition u_send_request.c:192
ulfius_send_http_streaming_request_max_header
int ulfius_send_http_streaming_request_max_header(const struct _u_request *request, struct _u_response *response, size_t(*write_body_function)(void *contents, size_t size, size_t nmemb, void *user_data), void *write_body_data, size_t max_header)
Definition u_send_request.c:281

## Send SMTP request API

The function ulfius_send_smtp_email is used to send emails using a smtp server. It is based on libcurl API. It's used to send plain/text emails via a smtp server. The function ulfius_send_smtp_rich_email is used to send an e-mail with a specified content-type.

The functions are defined as:

int ulfius_send_smtp_email(const char * host,
const int port,
const int use_tls,
const int verify_certificate,
const char * user,
const char * password,
const char * from,
const char * to,
const char * cc,
const char * bcc,
const char * subject,
const char * mail_body);
int ulfius_send_smtp_rich_email(const char * host,
const int port,
const int use_tls,
const int verify_certificate,
const char * user,
const char * password,
const char * from,
const char * to,
const char * cc,
const char * bcc,
const char * content_type,
const char * subject,
const char * mail_body);
ulfius_send_smtp_email
int ulfius_send_smtp_email(const char *host, const int port, const int use_tls, const int verify_certificate, const char *user, const char *password, const char *from, const char *to, const char *cc, const char *bcc, const char *subject, const char *mail_body)
Definition u_send_request.c:1028
ulfius_send_smtp_rich_email
int ulfius_send_smtp_rich_email(const char *host, const int port, const int use_tls, const int verify_certificate, const char *user, const char *password, const char *from, const char *to, const char *cc, const char *bcc, const char *content_type, const char *subject, const char *mail_body)
Definition u_send_request.c:824

# Miscellaneous functions

## Escape/Unescape string for url

Ulfius includes the functions ulfius_url_decode and ulfius_url_encode to transform a string into url-safe string and vice-versa. Both functions take a string in input and return a head-allocated string as output that must be u_free'd after use. Note: In the callback functions, the request->map_url values are already url-decoded by the framework.

char * ulfius_url_decode(const char * str);
char * ulfius_url_encode(const char * str);
ulfius_url_decode
char * ulfius_url_decode(const char *str)
Definition ulfius.c:1877
ulfius_url_encode
char * ulfius_url_encode(const char *str)
Definition ulfius.c:1843

## Export struct _u_request * and struct _u_response * in HTTP/1.1 stream format

Those functions can be useful to debug requests or responses, or can be used to demonstrate how their respective parameters are translated in HTTP language.

char * ulfius_export_request_http(const struct _u_request * request);
char * ulfius_export_response_http(const struct _u_response * response);
ulfius_export_response_http
char * ulfius_export_response_http(const struct _u_response *response)
Definition u_response.c:725
ulfius_export_request_http
char * ulfius_export_request_http(const struct _u_request *request)
Definition u_request.c:792

# struct _u_map API

The Structures _u_map is a simple key/value mapping API used in the requests and the response for setting parameters. The available functions to use this structure are:

int u_map_init(struct _u_map * map);
int u_map_clean(struct _u_map * u_map);
int u_map_clean_full(struct _u_map * u_map);
int u_map_clean_enum(char ** array);
const char ** u_map_enum_keys(const struct _u_map * u_map);
const char ** u_map_enum_values(const struct _u_map * u_map);
int u_map_has_key(const struct _u_map * u_map, const char * key);
int u_map_has_value(const struct _u_map * u_map, const char * value);
int u_map_has_value_binary(const struct _u_map * u_map, const char * value, size_t length);
int u_map_has_key_case(const struct _u_map * u_map, const char * key);
int u_map_has_value_case(const struct _u_map * u_map, const char * value);
int u_map_put(struct _u_map * u_map, const char * key, const char * value);
int u_map_put_binary(struct _u_map * u_map, const char * key, const char * value, uint64_t offset, size_t length);
size_t u_map_get_length(const struct _u_map * u_map, const char * key);
size_t u_map_get_case_length(const struct _u_map * u_map, const char * key);
const char * u_map_get(const struct _u_map * u_map, const char * key);
const char * u_map_get_case(const struct _u_map * u_map, const char * key);
int u_map_remove_from_key(struct _u_map * u_map, const char * key);
int u_map_remove_from_key_case(struct _u_map * u_map, const char * key);
int u_map_remove_from_value(struct _u_map * u_map, const char * value);
int u_map_remove_from_value_case(struct _u_map * u_map, const char * value);
int u_map_remove_from_value_binary(struct _u_map * u_map, const char * key, size_t length);
int u_map_remove_at(struct _u_map * u_map, const int index);
struct _u_map * u_map_copy(const struct _u_map * source);
int u_map_copy_into(const struct _u_map * source, struct _u_map * target);
int u_map_count(const struct _u_map * source);
u_map_init
int u_map_init(struct _u_map *u_map)
Definition u_map.c:32
u_map_remove_from_value_binary
int u_map_remove_from_value_binary(struct _u_map *u_map, const char *value, size_t length)
Definition u_map.c:296
u_map_remove_from_key
int u_map_remove_from_key(struct _u_map *u_map, const char *key)
Definition u_map.c:246
u_map_remove_at
int u_map_remove_at(struct _u_map *u_map, const int index)
Definition u_map.c:342
u_map_remove_from_value_case
int u_map_remove_from_value_case(struct _u_map *u_map, const char *value)
Definition u_map.c:319
u_map_get_case_length
ssize_t u_map_get_case_length(const struct _u_map *u_map, const char *key)
Definition u_map.c:447
u_map_remove_from_key_case
int u_map_remove_from_key_case(struct _u_map *u_map, const char *key)
Definition u_map.c:269
u_map_get_case
const char * u_map_get_case(const struct _u_map *u_map, const char *key)
Definition u_map.c:419
u_map_enum_values
const char ** u_map_enum_values(const struct _u_map *u_map)
Definition u_map.c:116
u_map_enum_keys
const char ** u_map_enum_keys(const struct _u_map *u_map)
Definition u_map.c:112
u_map_has_value
int u_map_has_value(const struct _u_map *u_map, const char *value)
Definition u_map.c:132
u_map_has_value_case
int u_map_has_value_case(const struct _u_map *u_map, const char *value)
Definition u_map.c:407
u_map_clean_enum
int u_map_clean_enum(char **array)
Definition u_map.c:98
u_map_clean_full
int u_map_clean_full(struct _u_map *u_map)
Definition u_map.c:89
u_map_has_key_case
int u_map_has_key_case(const struct _u_map *u_map, const char *key)
Definition u_map.c:395
u_map_copy_into
int u_map_copy_into(struct _u_map *dest, const struct _u_map *source)
Definition u_map.c:489
u_map_put
int u_map_put(struct _u_map *u_map, const char *key, const char *value)
Definition u_map.c:148
u_map_has_value_binary
int u_map_has_value_binary(const struct _u_map *u_map, const char *value, size_t length)
Definition u_map.c:136
u_map_has_key
int u_map_has_key(const struct _u_map *u_map, const char *key)
Definition u_map.c:120
u_map_remove_from_value
int u_map_remove_from_value(struct _u_map *u_map, const char *value)
Definition u_map.c:292
u_map_put_binary
int u_map_put_binary(struct _u_map *u_map, const char *key, const char *value, uint64_t offset, size_t length)
Definition u_map.c:156
u_map_count
int u_map_count(const struct _u_map *source)
Definition u_map.c:507
u_map_copy
struct _u_map * u_map_copy(const struct _u_map *source)
Definition u_map.c:461

# What's new in Ulfius 2.7?

Allow Content-Enconding header with ulfius_send_http_request to compress the response body Add http_compression callback example Add static_compressed_inmemory_website callback example Add callback return value U_CALLBACK_IGNORE to igore incrementation of request->callback_position Add ulfius_add_websocket_extension_message_perform and ulfius_add_websocket_client_extension_message_perform for advanced websocket extensions management Add Compression Extensions for WebSocket

## Breaking change with struct _websocket_client_handler

When declaring a Structures _websocket_client_handler for websocket client API, you must initialize its members content to NULL before using it:

struct _websocket_client_handler websocket_client_handler = {NULL, NULL};

## Breaking change with ulfius_set_websocket_response

When using ulfius_set_websocket_response with parameters websocket_protocol or websocket_extensions set to NULL, Ulfius will no longer accept any protocol or extension sent by the client, but will return no extension nor protocol to the client, and the websocket connexion will be "raw".

# What's new in Ulfius 2.6?

Add IPv6 support.

Add Structures _u_request->callback_position to know the position of the current callback in the callback list.

# What's new in Ulfius 2.5?

Add option to ignore non UTF8 strings in incoming requests.

Allow client certificate authentication

# What's new in Ulfius 2.4?

Improve websocket service features with lots of bugfixes and add the possibility to send a fragmented message.

Add websocket client functionality. Allow to create a websocket client connection and exchange messages with the websocket service. In http:///ws:// non-secure mode or https:///wss:// secure mode.

Add a command-line websocket client: uwsc.

# What's new in Ulfius 2.3?

Not much on the API, a lot on the build process. Install via CMake script.

# What's new in Ulfius 2.2?

Allow to use your own callback function when uploading files with ulfius_set_upload_file_callback_function, so a large file can be uploaded, even with the option Structures _u_instance.max_post_param_size set.

# What's new in Ulfius 2.1?

I know it wasn't long since Ulfius 2.0 was released. But after some review and tests, I realized some adjustments had to be made to avoid bugs and to clean the framework a little bit more.

Some of the adjustments made in the new release:

- An annoying bug has been fixed that made streaming data a little buggy when used on Raspbian. Now if you don't know the data size you're sending, use the macro U_STREAM_SIZE_UNKNOWN instead of the previous value -1. There is some updates in the stream callback function parameter types. Check the streaming data documentation.
- Fix bug on ulfius_send_http_request that didn't send back all headers value with the same name (#19)
- Fix websocket declaration structures to have them outside of the ulfius.h, because it could lead to horrifying bugs when you compile Ulfius with websocket but add #define U_DISABLE_WEBSOCKET in your application.
- Add proxy value for outgoing requests (#18)
- Unify and update functions name ulfius_set_[string|json|binary]_body. You may have to update your legacy code.

The minor version number has been incremented, from 2.0 to 2.1 because some of the changes may require changes in your own code.

# What's new in Ulfius 2.0?

Ulfius 2.0 brings several changes that make the library incompatible with Ulfius 1.0.x branch. The goal of making Ulfius 2.0 is to make a spring cleaning of some functions, remove what is apparently useless, and should bring bugs and memory loss. The main new features are multiple callback functions and websockets implementation.

## Multiple callback functions

Instead of having an authentication callback function, then a main callback function, you can now have as much callback functions as you want for the same endpoint. A priority number has been added in the Structures _u_endpoint and the auth_callback function and its dependencies have been removed.

For example, let's say you have the following endpoints defined:

- GET /api/tomato/:tomato => tomato_get_callback function, priority 10
- GET /api/potato/:potato => potato_get_callback function, priority 10
- GET /api/* => api_validate_callback function, priority 5
- * * => authentication_callback function, priority 1
- GET * => gzip_body_callback function, priority 99

Then if the client calls the URL GET /api/potato/myPotato, the following callback functions will be called in that order:

- authentication_callback
- api_validate_callback
- potato_get_callback
- gzip_body_callback

Warning: In this example, the URL parameter myPotato will be available only in the potato_get_callback function, because the other endpoints did not defined a URL parameter after /potato.

If you need to communicate between callback functions for any purpose, you can use the new parameter Structures _u_response.shared_data. This is a void * pointer initialized to NULL.

The dedicated function ulfius_set_response_shared_data can be used to set Structures _u_response.shared_data and Structures _u_response.free_shared_data. If Structures _u_response.free_shared_data is set, the function will be used to free Structures _u_response.shared_data at the end of the callback list.

Note: If you call ulfius_set_response_shared_data multiple times in the same request, before replacing _u_response.shared_data, the function ulfius_set_response_shared_data will free the previous pointer with the previous Structures _u_response.free_shared_data if set.

## Keep only binary_body in struct _u_request and struct _u_response

the values string_body and json_body have been removed from the structures Structures _u_request and Structures _u_response. This may be painless in the response if you used only the functions ulfius_set_xxx_body_response. Otherwise, you should make small arrangements to your code.

## Websocket service

Ulfius now allows websockets communication between the client and the server. Check the API.md file for implementation details.

Using websocket requires libgnutls. It also requires a recent version of Libmicrohttpd, at least 0.9.53.

If you don't need or can't use this feature, you can disable it by adding the option WEBSOCKETFLAG=1 to the make command when you build Ulfius:

$ make WEBSOCKETFLAG=1

## Remove libjansson and libcurl hard dependency

In Ulfius 1.0, libjansson and libcurl were mandatory to build the library, but their usage was not in the core of the framework. Although they can be very useful, so the dependency is now optional.

They are enabled by default, but if you don't need them, you can disable them when you build Ulfius library.

### libjansson dependency

This dependency allows to use the following functions:

json_t * ulfius_get_json_body_request(const struct _u_request * request, json_error_t * json_error);
int ulfius_set_json_body_request(struct _u_request * request, json_t * body);
int ulfius_set_json_body_response(struct _u_response * response, const unsigned int status, const json_t * body);
json_t * ulfius_get_json_body_response(struct _u_response * response, json_error_t * json_error);

If you want to disable these functions, append JANSSONFLAG=1 when you build Ulfius library.

$ git clone https://github.com/babelouest/ulfius.git
$ cd ulfius/
$ git submodule update --init
$ make JANSSONFLAG=1
$ sudo make install

### libcurl dependency

This dependency allows to use the following functions:

int ulfius_send_http_request(const struct _u_request * request, struct _u_response * response);
int ulfius_send_http_streaming_request(const struct _u_request * request, struct _u_response * response, size_t (* write_body_function)(void * contents, size_t size, size_t nmemb, void * user_data), void * write_body_data);
int ulfius_send_smtp_email(const char * host,
const int port,
const int use_tls,
const int verify_certificate,
const char * user,
const char * password,
const char * from,
const char * to,
const char * cc,
const char * bcc,
const char * subject,
const char * mail_body);
int ulfius_send_smtp_rich_email(const char * host,
const int port,
const int use_tls,
const int verify_certificate,
const char * user,
const char * password,
const char * from,
const char * to,
const char * cc,
const char * bcc,
const char * content_type,
const char * subject,
const char * mail_body);

If you want to disable these functions, append CURLFLAG=1 when you build Ulfius library.

$ git clone https://github.com/babelouest/ulfius.git
$ cd ulfius/
$ git submodule update --init
$ make CURLFLAG=1
$ sudo make install

If you wan to disable libjansson and libcurl, you can append both parameters.

$ git clone https://github.com/babelouest/ulfius.git
$ cd ulfius/
$ git submodule update --init
$ make CURLFLAG=1 JANSSONFLAG=1
$ sudo make install

## Ready-to-use callback functions

You can find some ready-to-use callback functions in the folder example_callbacks.

# Update existing programs from Ulfius 2.0 to 2.1

- An annoying bug has been fixed that made streaming data a little buggy when used on Raspbian. Now if you don't know the data size you're sending, use the macro U_STREAM_SIZE_UNKNOWN instead of the previous value -1.
- There are some updates in the stream callback function parameter types. Check the streaming data documentation.
- The websocket data structures are no longer available directly in Structures _u_response or Structures _u_instance. But you shouldn't use them like this anyway so it won't be a problem.
- Unify and update functions name ulfius_set_*_body_response. You may have to update your legacy code. The new functions names are:
  int ulfius_set_string_body_response(struct _u_response * response, const unsigned int status, const char * body);
  int ulfius_set_binary_body_response(struct _u_response * response, const unsigned int status, const char * body, const size_t length);
  int ulfius_set_empty_body_response(struct _u_response * response, const unsigned int status);
  ulfius_set_binary_body_response
  int ulfius_set_binary_body_response(struct _u_response *response, const unsigned int status, const char *binary_body, const size_t length)
  Definition u_response.c:534

# Update existing programs from Ulfius 1.x to 2.0

If you already have programs that use Ulfius 1.x and want to update them to the brand new fresh Ulfius 2.0, it may require the following minor changes.

## Endpoints definitions

Endpoints structure have changed, ulfius_add_endpoint_by_val now requires only one callback function, but requires a priority number.

If you don't use authentication callback functions, you can simply remove the NULL, NULL, NULL parameters corresponding to the former authentication callback function pointer, the authentication callback user data, and the realm value. Then add any number as a priority, 0 for example.

If you use authentication callback functions, split your ulfius_add_endpoint_by_val call in 2 separate calls, one for the authentication function, one for the main callback function. For example:

// An Ulfius 1.x call
ulfius_add_endpoint_by_val(&instance, "GET", "/", NULL, &auth_callback, my_auth_data, "my realm", &main_callback, my_main_data);
// The same behaviour with Ulfius 2.0
ulfius_add_endpoint_by_val(&instance, "GET", "/", NULL, 0, &auth_callback, my_auth_data);
ulfius_add_endpoint_by_val(&instance, "GET", "/", NULL, 1, &main_callback, my_main_data);
// In this case, the realm value "my realm" must be specified in the response

## Callback return value

The return value for the callback functions must be adapted, instead of U_OK, U_ERROR or U_ERROR_UNAUTHORIZED, you must use one of the following:

#define U_CALLBACK_CONTINUE 0 // Will replace U_OK
#define U_CALLBACK_IGNORE 1
#define U_CALLBACK_COMPLETE 2
#define U_CALLBACK_UNAUTHORIZED 3 // Will replace U_ERROR_UNAUTHORIZED
#define U_CALLBACK_ERROR 4 // Will replace U_ERROR

If you want more details on the multiple callback functions, check the documentation.

Other functions may have change their name or signature, check the documentation for more information.