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 *mhd_ops)
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_instance	the ulfius instance to initialize
port	tcp port to bind to, must be between 1 and 65535
bind_address	IPv4 address to listen to, optional, the reference is borrowed, the structure isn't copied
default_auth_realm	default 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_instance

an 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_instance

pointer 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_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

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_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

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_instance	pointer to a struct _u_instance that describe its port and bind address
mhd_flags	OR-ed combination of MHD_FLAG values
mhd_ops	struct 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_instance

pointer 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_instance	pointer to a struct _u_instance that describe its port and bind address
file_upload_callback	Pointer to a callback function that will handle all file uploads
cls	a pointer that will be passed to file_upload_callback each tim it's called

Returns

U_OK on success