Ulfius
HTTP Framework for REST Applications in C
Functions
struct _u_instance

Functions

int ulfius_init_instance (struct _u_instance *u_instance, unsigned int port, struct sockaddr_in *bind_address, const char *default_auth_realm)
 
void ulfius_clean_instance (struct _u_instance *u_instance)
 
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)
 
void mhd_request_completed (void *cls, struct MHD_Connection *connection, void **con_cls, enum MHD_RequestTerminationCode toe)
 
void * ulfius_uri_logger (void *cls, const char *uri)
 
int ulfius_stop_framework (struct _u_instance *u_instance)
 
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)
 

Detailed Description

struct _u_instance management functions

Function Documentation

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

ulfius_init_instance

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

Parameters
u_instancethe ulfius instance to initialize
porttcp port to bind to, must be between 1 and 65535
bind_addressIPv4 address to listen to, optional, the reference is borrowed, the structure isn't copied
default_auth_realmdefault realm to send to the client on authentication error
Returns
U_OK on success

◆ ulfius_clean_instance()

void ulfius_clean_instance ( struct _u_instance u_instance)

ulfius_clean_instance

Clean memory allocated by a struct _u_instance *

Parameters
u_instancean Ulfius instance

◆ ulfius_start_framework()

int ulfius_start_framework ( struct _u_instance u_instance)

ulfius_start_framework Initializes the framework and run the webservice based on the parameters given

Parameters
u_instancepointer to a struct _u_instance that describe its port and bind address
Returns
U_OK on success

ulfius_start_framework Initializes the framework and run the webservice based on the parameters given return true if no error

u_instance: pointer to a struct _u_instance that describe its port and bind address return U_OK on success

◆ ulfius_start_secure_framework()

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

ulfius_start_secure_framework Initializes the framework and run the webservice based on the parameters given using an HTTPS connection

Parameters
u_instancepointer to a struct _u_instance that describe its port and bind address
key_pemprivate key for the server
cert_pemserver certificate
Returns
U_OK on success

ulfius_start_secure_framework Initializes the framework and run the webservice based on the parameters given using an HTTPS connection

u_instance: pointer to a struct _u_instance that describe its port and bind address key_pem: private key for the server cert_pem: server certificate return U_OK on success

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

ulfius_start_secure_ca_trust_framework Initializes the framework and run the webservice based on the parameters given using an HTTPS connection And using a root server to authenticate client connections

Parameters
u_instancepointer to a struct _u_instance that describe its port and bind address
key_pemprivate key for the server
cert_pemserver certificate
root_ca_pemclient root CA you're willing to trust for this instance
Returns
U_OK on success

ulfius_start_secure_ca_trust_framework Initializes the framework and run the webservice based on the parameters given using an HTTPS connection And using a root server to authenticate client connections

u_instance: pointer to a struct _u_instance that describe its port and bind address key_pem: private key for the server cert_pem: server certificate root_ca_pem: client root CA you're willing to trust for this instance return U_OK on success

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

ulfius_start_framework_with_mhd_options Initializes the framework and run the webservice based on the specified MHD options table given in parameter Read https://www.gnu.org/software/libmicrohttpd/tutorial.html for more information This is for user who know what they do, Ulfius' options used in other ulfius_start_framework_* are good for most use cases where you need a multi-threaded HTTP webservice Some struct MHD_OptionItem may cause unexpected problems with Ulfius API If you find an unresolved issue with this function you can open an issue in GitHub But some issues may not be solvable if fixing them would break Ulfius API or philosophy i.e.: you're on your own

Parameters
u_instancepointer to a struct _u_instance that describe its port and bind address
mhd_flagsOR-ed combination of MHD_FLAG values
mhd_opsstruct MHD_OptionItem * options table,
  • MUST contain an option with the fllowing value: {.option = MHD_OPTION_NOTIFY_COMPLETED; .value = (intptr_t)mhd_request_completed; .ptr_value = NULL;}
  • MUST contain an option with the fllowing value: {.option = MHD_OPTION_URI_LOG_CALLBACK; .value = (intptr_t)ulfius_uri_logger; .ptr_value = NULL;}
  • MUST end with a terminal struct MHD_OptionItem: {.option = MHD_OPTION_END; .value = 0; .ptr_value = NULL;}
Returns
U_OK on success

ulfius_start_framework_with_mhd_options Initializes the framework and run the webservice based on the specified MHD options table given in parameter Read https://www.gnu.org/software/libmicrohttpd/tutorial.html for more information This is for user who know what they do, Ulfius' options used in other ulfius_start_framework_* are good for most use cases where you need a multi-threaded HTTP webservice Some struct MHD_OptionItem may cause unexpected problems with Ulfius API If you find an unresolved issue with this function you can open an issue in GitHub But some issues may not be solvable if fixing them would break Ulfius API or philosophy i.e.: you're on your own

Parameters
u_instancepointer to a struct _u_instance that describe its port and bind address
mhd_flagsOR-ed combination of MHD_FLAG values
mhd_opsstruct MHD_OptionItem * options table
  • MUST contain an option with the fllowing value: {.option = MHD_OPTION_NOTIFY_COMPLETED; .value = (intptr_t)mhd_request_completed; .ptr_value = NULL;}
  • MUST contain an option with the fllowing value: {.option = MHD_OPTION_URI_LOG_CALLBACK; .value = (intptr_t)ulfius_uri_logger; .ptr_value = NULL;}
  • MUST end with a terminal struct MHD_OptionItem: {.option = MHD_OPTION_END; .value = 0; .ptr_value = NULL;}
Returns
U_OK on success

◆ mhd_request_completed()

void mhd_request_completed ( void *  cls,
struct MHD_Connection *  connection,
void **  con_cls,
enum MHD_RequestTerminationCode  toe 
)

Internal functions externalized to use ulfius_start_framework_with_mhd_options

mhd_request_completed function used to clean data allocated after a web call is complete

◆ ulfius_uri_logger()

void* ulfius_uri_logger ( void *  cls,
const char *  uri 
)

Internal method used to duplicate the full url before it's manipulated and modified by MHD

◆ ulfius_stop_framework()

int ulfius_stop_framework ( struct _u_instance u_instance)

ulfius_stop_framework

Stop the webservice

Parameters
u_instancepointer to a struct _u_instance that describe its port and bind address
Returns
U_OK on success

ulfius_stop_framework

Stop the webservice u_instance: pointer to a struct _u_instance that describe its port and bind address return U_OK on success

◆ ulfius_set_upload_file_callback_function()

int ulfius_set_upload_file_callback_function ( struct _u_instance u_instance,
int(*)(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)  file_upload_callback,
void *  cls 
)

ulfius_set_upload_file_callback_function

Set the callback function to handle file upload Used to facilitate large files upload management The callback function file_upload_callback will be called multiple times, with the uploaded file in striped in parts

Warning: If this function is used, all the uploaded files for the instance will be managed via this function, and they will no longer be available in the struct _u_request in the ulfius callback function afterwards.

Thanks to Thad Phetteplace for the help on this feature

Parameters
u_instancepointer to a struct _u_instance that describe its port and bind address
file_upload_callbackPointer to a callback function that will handle all file uploads
clsa pointer that will be passed to file_upload_callback each tim it's called
Returns
U_OK on success