Ulfius: struct _u_instance

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

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