mihl.h File Reference

Detailed Description

Definition in file mihl.h.

Include dependency graph for mihl.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct mihl_cnxinfo_t

Typedefs

typedef int SOCKET

typedef struct mihl_ctx mihl_ctx_t

typedef struct mihl_cnx mihl_cnx_t

typedef int( mihl_pf_handle_get_t )(mihl_cnx_t *, char const *, char const *, void *)

typedef int( mihl_pf_handle_post_t )(mihl_cnx_t *, char const *, char const *, int, char **, char **, void *)

typedef enum mihl_log_level mihl_log_level_t

Enumerations

enum mihl_log_level {
MIHL_LOG_ERROR = 0x01, MIHL_LOG_WARNING = 0x02, MIHL_LOG_INFO = 0x04, MIHL_LOG_INFO_VERBOSE = 0x08,
MIHL_LOG_DEBUG = 0x10
}

Functions

mihl_ctx_t * mihl_get_ctx (mihl_cnx_t *cnx)

Utility function to return the Connexion Context, which is the value given by mihl_init().

int mihl_log (mihl_ctx_t *, unsigned level, const char *fmt,...)

TBD.

mihl_ctx_t * mihl_init (char const *bind_addr, int port, int maxnb_cnx, unsigned log_level)

Library initializations: start waiting for HTTP connections.

int mihl_end (mihl_ctx_t *)

This function is the opposite of mish_init(): it close all current open HTTP connections, and release all resources that might have been allocated.

int mihl_server (mihl_ctx_t *)

Manage new connections, existent connections, and connections timeout.

int mihl_add (mihl_cnx_t *cnx, char const *fmt,...)

Build HTML page for a given HTTP URL.

int mihl_send (mihl_cnx_t *cnx, char const *answer, char const *fmt_header,...)

TBD.

int mihl_handle_get (mihl_ctx_t *ctx, char const *tag, mihl_pf_handle_get_t *pf, void *param)

Provide a C function handler for a GET operation.

int mihl_handle_post (mihl_ctx_t *ctx, char const *tag, mihl_pf_handle_post_t *pf, void *param)

Provide a C function handler for a POST operation.

int mihl_handle_file (mihl_ctx_t *ctx, char const *tag, char const *filename, char const *content_type, int close_connection)

This function is used to describe a file that will be served for a given HTTP request.

int mihl_info (mihl_ctx_t *ctx, int maxnb_cnxinfos, mihl_cnxinfo_t *infos)

Provide information on current connections.

void mihl_set_log_level (mihl_ctx_t *, mihl_log_level_t level)

TBD.

mihl_log_level_t mihl_get_log_level (mihl_ctx_t *)

TBD.

int mihl_dump_info (mihl_ctx_t *)

TBD.

int mihl_dump_info_handlers (mihl_ctx_t *ctx)

TBD.

int send_file (mihl_cnx_t *cnx, char const *tag, char const *filename, char *content_type, int close_connection)

TBD.

char * mihl_authorization (mihl_cnx_t *cnx)

TBD.

void mihl_base64_encode (char const *bin, size_t size, char *bout, size_t maxlen)

Base64 encode function.

void mihl_base64_decode (char const *bin, size_t size, char *bout, size_t maxlen)

Base64 decode function.

Function Documentation

mihl_ctx_t* mihl_get_ctx ( mihl_cnx_t * cnx )

Utility function to return the Connexion Context, which is the value given by mihl_init().

Parameters:

cnx

opaque context structure as returned by mihl_init()

Returns:: Connexion context as given by mihl_init()

Definition at line 255 of file mihl.c.

int mihl_log	(	mihl_ctx_t *	ctx,
		unsigned	level,
		const char *	fmt,
			...
	)

TBD.

Parameters:

	ctx	opaque context structure as returned by mihl_init()
	level	MIHL_LOG_ERROR \| MIHL_LOG_WARNING \| MIHL_LOG_INFO \|
	fmt	TBD
	...	TBD

Returns:: TBD

Definition at line 800 of file mihl.c.

Referenced by mihl_dump_info(), mihl_dump_info_handlers(), and send_file().

Here is the caller graph for this function:

mihl_ctx_t* mihl_init	(	char const *	bind_addr,
		int	port,
		int	maxnb_cnx,
		unsigned	log_level
	)

Library initializations: start waiting for HTTP connections.

Initializes the library internally.

Typically, next library calls will be functions such as mihl_handle_get or mihl_handle_file.

Parameters:

	bind_addr	Address on which the connections will be established. NULL means INADDR_ANY.
	port	TCP port used for the HTTP connection. 80 is the standard port, but any other port not yet in use might be used, assuming you have sufficient privileges
	maxnb_cnx	maximum number of allowed connections. If you did not installed your own handler, a standard page will be displayed if you have a number of connections exceeds the maximum number allowed.
	log_level	initial log level (can be changed later with mihl_set_log_level.

Returns:

an opaque context structure used by all further calls. This enables to run several instances of the embedded server.
or NULL, if the operation failed

Note:: Besides internal library initializations, this function performs bind() then listen().

Definition at line 210 of file mihl.c.

References mihl_handle_get().

Here is the call graph for this function:

int mihl_end ( mihl_ctx_t * ctx )

This function is the opposite of mish_init(): it close all current open HTTP connections, and release all resources that might have been allocated.

All the sockets in use are closed.

Parameters:

ctx

context structure as returned by mihl_init()

Returns:

number of connections closed (which might be 0)
or -1 if an error occurred (errno is then set).

Definition at line 268 of file mihl.c.

int mihl_server ( mihl_ctx_t * ctx )

Manage new connections, existent connections, and connections timeout.

MIHL is based on a non-blocking and single thread mode; therefore you’ll have to call this function on a frequent basis in order to:

establish new connections;
serve pages for existent connections;
and finally close timed out connections.

In the case of an existent connection, typically a user-provided callback function is called. Its job is to build a new page which is then sent to the client. In a single-thread model, each of these functions should not take too much time: the next callback function will be ‘scheduled’ only when the current function is done (sort of a ‘cooperative multi-tasking’).

Parameters:

ctx

opaque context structure as returned by mihl_init()

Returns:: The current number of active connexions.

Note:: Remember that this is a non blocking call. If you do not call this function, no new connection can be established.

Definition at line 763 of file mihl.c.

int mihl_add	(	mihl_cnx_t *	cnx,
		char const *	fmt,
			...
	)

Build HTML page for a given HTTP URL.

Used within a C handler function (such as one provide to mihl_handle_get or mihl_handle_post), to build a page content. Once the page will is finished, a call to mihl_add should be done.

Parameters:

	cnx	Opaque pointer, as provided to the C handler function (GET).
	fmt	printf like format and optional arguments to describe the data to add into the page (typically HTML content).
	...	Optional printf like format arguments

Returns:

0 if the operation succeeded
or -1 if an error occurred (errno is then set).

Note:: mihl_add and mihl_send use a dynamic buffer, which is allocated when needed, but only released with mihl_end().

Definition at line 261 of file tcp_utils.c.

int mihl_send	(	mihl_cnx_t *	cnx,
		char const *	answer,
		char const *	fmt_header,
			...
	)

TBD.

Parameters:

	cnx	opaque context structure as returned by mihl_init()
`[in]`	answer	HTTP answer to send, If NULL, will send "HTTP/1.1 200 OK\r\n"
	fmt_header	TBD
	...	TBD

Returns:

X
or -1 if an error occurred (errno is then set).

Definition at line 289 of file tcp_utils.c.

References tcp_write().

Here is the call graph for this function:

int mihl_handle_get	(	mihl_ctx_t *	ctx,
		char const *	tag,
		mihl_pf_handle_get_t *	pf,
		void *	param
	)

Provide a C function handler for a GET operation.

The mihl_handle_get() function installs a C handler function that will be used to construct an HTTP page for a given URL.

Parameters:

	ctx	opaque context structure as returned by mihl_init()
	tag	HTTP base URL (such as “/” or ‘/nextpage.html”). If this is NULL, the handler will be called for every non found page.
	pf	pointer to the C handler function that will be called for this particular HTTP URL.
	param	user pointer that will be provided to the C handler function.

Returns:

0 if the operation succeeded
or -1 if an error occurred (errno is then set)

Definition at line 634 of file mihl.c.

Referenced by mihl_init().

Here is the caller graph for this function:

int mihl_handle_post	(	mihl_ctx_t *	ctx,
		char const *	tag,
		mihl_pf_handle_post_t *	pf,
		void *	param
	)

Provide a C function handler for a POST operation.

The mihl_handle_get() function installs a C handler function that will be used to construct an HTTP page for a given URL

Parameters:

	ctx	opaque context structure as returned by mihl_init()
	tag	HTTP base URL (such as “/” or ‘/nextpage.html”).
	pf	pointer to the C handler function that will be called for this particular HTTP URL.
	param	user pointer that will be provided to the C handler function.

Returns:

0 if the operation succeeded
or -1 if an error occurred (errno is then set)

Definition at line 683 of file mihl.c.

int mihl_handle_file	(	mihl_ctx_t *	ctx,
		char const *	tag,
		char const *	filename,
		char const *	content_type,
		int	close_connection
	)

This function is used to describe a file that will be served for a given HTTP request.

Parameters:

	ctx	opaque context structure as returned by mihl_init()
	tag	HTTP base URL (such as “/image.jpg” for instance)
	filename	ilename to send. The full pathname can be given.
	content_type	HTTP content type, such as “image/jpeg”, “image/gif”, “text/javascript”, etc.
	close_connection	indicate if the HTTP connection should be closed or not.

Returns:

the number of defined handles if the operation succeeded,
or -1 if an error occurred (errno is then set).

Definition at line 719 of file mihl.c.

int mihl_info	(	mihl_ctx_t *	ctx,
		int	maxnb_cnxinfos,
		mihl_cnxinfo_t *	infos
	)

Provide information on current connections.

Parameters:

	ctx	opaque context structure as returned by mihl_init()
	maxnb_cnxinfos	TBD
	infos	TBD

Returns:

number of connections which are documented (which might be 0)
or -1 if an error occurred (errno is then set).

Definition at line 855 of file mihl.c.

void mihl_set_log_level	(	mihl_ctx_t *	ctx,
		mihl_log_level_t	level
	)

TBD.

Parameters:

	ctx	opaque context structure as returned by mihl_init()
	level	Specify which log levels we are interested in

Definition at line 777 of file mihl.c.

mihl_log_level_t mihl_get_log_level ( mihl_ctx_t * ctx )

TBD.

Parameters:

ctx

opaque context structure as returned by mihl_init()

Returns:: Specify which log levels we are interested in

Definition at line 787 of file mihl.c.

int mihl_dump_info ( mihl_ctx_t * ctx )

TBD.

Parameters:

ctx

opaque context structure as returned by mihl_init()

Returns:: The number of active connexions

Definition at line 817 of file mihl.c.

References mihl_log().

Here is the call graph for this function:

int mihl_dump_info_handlers ( mihl_ctx_t * ctx )

TBD.

Parameters:

ctx

opaque context structure as returned by mihl_init()

Returns:: The number of active connexions

Definition at line 876 of file mihl.c.

References mihl_log().

Here is the call graph for this function:

int send_file	(	mihl_cnx_t *	cnx,
		char const *	tag,
		char const *	filename,
		char *	content_type,
		int	close_connection
	)

TBD.

Parameters:

	cnx	opaque context structure as returned by mihl_init()
	tag	TBD
	filename	TBD
	content_type	TBD
	close_connection	TBD

Returns:: TBD

Definition at line 283 of file mihl.c.

References mihl_log(), read_file(), and tcp_write().

Here is the call graph for this function:

char* mihl_authorization ( mihl_cnx_t * cnx )

TBD.

Parameters:

ctx

opaque context structure as returned by mihl_init()

Returns:: Value of the string 'Authorization:' if found, or NULL if not found

Definition at line 912 of file mihl.c.

void mihl_base64_encode	(	char const *	bin,
		size_t	size,
		char *	bout,
		size_t	maxlen
	)

Base64 encode function.

Parameters:

`[in]`	bin	Input buffer: string to encode
	size	Number of bytes in the input string
`[out]`	Buffer	to store the Base64 encoded output string
	maxlen	Max length for the encoded output string

Definition at line 67 of file b64.c.

void mihl_base64_decode	(	char const *	bin,
		size_t	size,
		char *	bout,
		size_t	maxlen
	)

Base64 decode function.

Parameters:

`[in]`	bin	Base64 encoded input string
	size	Number of bytes in the encoded input string
`[out]`	Buffer	to store the decoded output string
	maxlen	Max length for the decoded output string

Definition at line 112 of file b64.c.


Data Structures
struct	mihl_cnxinfo_t
Typedefs
typedef int	SOCKET
typedef struct mihl_ctx	mihl_ctx_t
typedef struct mihl_cnx	mihl_cnx_t
typedef int(	mihl_pf_handle_get_t )(mihl_cnx_t , char const , char const , void )
typedef int(	mihl_pf_handle_post_t )(mihl_cnx_t , char const , char const , int, char , char , void )
typedef enum mihl_log_level	mihl_log_level_t
Enumerations
enum	mihl_log_level { MIHL_LOG_ERROR = 0x01, MIHL_LOG_WARNING = 0x02, MIHL_LOG_INFO = 0x04, MIHL_LOG_INFO_VERBOSE = 0x08, MIHL_LOG_DEBUG = 0x10 }
Functions
mihl_ctx_t *	mihl_get_ctx (mihl_cnx_t *cnx)
	Utility function to return the Connexion Context, which is the value given by mihl_init().
int	mihl_log (mihl_ctx_t , unsigned level, const char fmt,...)
	TBD.
mihl_ctx_t *	mihl_init (char const *bind_addr, int port, int maxnb_cnx, unsigned log_level)
	Library initializations: start waiting for HTTP connections.
int	mihl_end (mihl_ctx_t *)
	This function is the opposite of mish_init(): it close all current open HTTP connections, and release all resources that might have been allocated.
int	mihl_server (mihl_ctx_t *)
	Manage new connections, existent connections, and connections timeout.
int	mihl_add (mihl_cnx_t cnx, char const fmt,...)
	Build HTML page for a given HTTP URL.
int	mihl_send (mihl_cnx_t cnx, char const answer, char const *fmt_header,...)
	TBD.
int	mihl_handle_get (mihl_ctx_t ctx, char const tag, mihl_pf_handle_get_t pf, void param)
	Provide a C function handler for a GET operation.
int	mihl_handle_post (mihl_ctx_t ctx, char const tag, mihl_pf_handle_post_t pf, void param)
	Provide a C function handler for a POST operation.
int	mihl_handle_file (mihl_ctx_t ctx, char const tag, char const filename, char const content_type, int close_connection)
	This function is used to describe a file that will be served for a given HTTP request.
int	mihl_info (mihl_ctx_t ctx, int maxnb_cnxinfos, mihl_cnxinfo_t infos)
	Provide information on current connections.
void	mihl_set_log_level (mihl_ctx_t *, mihl_log_level_t level)
	TBD.
mihl_log_level_t	mihl_get_log_level (mihl_ctx_t *)
	TBD.
int	mihl_dump_info (mihl_ctx_t *)
	TBD.
int	mihl_dump_info_handlers (mihl_ctx_t *ctx)
	TBD.
int	send_file (mihl_cnx_t cnx, char const tag, char const filename, char content_type, int close_connection)
	TBD.
char *	mihl_authorization (mihl_cnx_t *cnx)
	TBD.
void	mihl_base64_encode (char const bin, size_t size, char bout, size_t maxlen)
	Base64 encode function.
void	mihl_base64_decode (char const bin, size_t size, char bout, size_t maxlen)
	Base64 decode function.