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.

Typedef Documentation

typedef int SOCKET

Definition at line 26 of file mihl.h.

typedef struct mihl_ctx mihl_ctx_t

Definition at line 28 of file mihl.h.

typedef struct mihl_cnx mihl_cnx_t

Definition at line 30 of file mihl.h.

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

Definition at line 32 of file mihl.h.

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

Definition at line 34 of file mihl.h.

typedef enum mihl_log_level mihl_log_level_t

Enumeration Type Documentation

enum mihl_log_level

Enumerator:

MIHL_LOG_ERROR
MIHL_LOG_WARNING
MIHL_LOG_INFO
MIHL_LOG_INFO_VERBOSE
MIHL_LOG_DEBUG

Definition at line 68 of file mihl.h.

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.

References mihl_cnx::ctx.

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.

References mihl_ctx::log_level.

Referenced by add_new_connexion(), bind_and_listen(), delete_connexion(), got_data_for_active_connexion(), manage_new_connexions(), 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_cnx::active, mihl_ctx::bind_addr, bind_and_listen(), mihl_ctx::connexions, mihl_cnx::ctx, mihl_ctx::handles, mihl_ctx::log_level, mihl_ctx::maxnb_cnx, mihl_handle_get(), mihl_ctx::nb_connexions, mihl_ctx::nb_handles, page_not_found(), mihl_ctx::port, mihl_ctx::read_buffer, and mihl_ctx::read_buffer_maxlen.

Referenced by main().

Here is the call graph for this function:

Here is the caller 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.

References FREE, and mihl_ctx::read_buffer.

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.

References manage_existent_connexions(), manage_new_connexions(), manage_timedout_connexions(), and mihl_ctx::nb_connexions.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

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.

References mihl_cnx::html_buffer, mihl_cnx::html_buffer_len, and mihl_cnx::html_buffer_sz.

Referenced by http_data(), http_root(), and page_not_found().

Here is the caller graph for this function:

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 ERRNO, mihl_cnx::html_buffer, mihl_cnx::html_buffer_len, mihl_cnx::sockfd, and tcp_write().

Referenced by http_data(), http_root(), and page_not_found().

Here is the call graph for this function:

Here is the caller 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.

References migl_handle::filename, FREE, mihl_ctx::handles, mihl_handle_get_add(), mihl_ctx::nb_handles, migl_handle::partial, migl_handle::pf_get, migl_handle::pf_post, and migl_handle::tag.

Referenced by main(), and mihl_init().

Here is the call graph for this function:

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.

References migl_handle::close_connection, migl_handle::content_type, migl_handle::filename, mihl_ctx::handles, mihl_ctx::nb_handles, migl_handle::param, migl_handle::partial, migl_handle::pf_get, migl_handle::pf_post, and migl_handle::tag.

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.

References migl_handle::close_connection, migl_handle::content_type, migl_handle::filename, mihl_ctx::handles, mihl_ctx::nb_handles, migl_handle::partial, migl_handle::pf_get, migl_handle::pf_post, and migl_handle::tag.

Referenced by main().

Here is the caller graph for this function:

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.

References mihl_cnx::active, mihl_ctx::connexions, mihl_cnx::info, and mihl_ctx::maxnb_cnx.

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.

References mihl_ctx::log_level.

Referenced by peek_key().

Here is the caller graph for this function:

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.

References mihl_ctx::log_level.

Referenced by peek_key().

Here is the caller graph for this function:

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_cnx::active, mihl_cnxinfo_t::client_addr, mihl_ctx::connexions, mihl_cnx::info, mihl_cnxinfo_t::last_request, mihl_ctx::log_level, mihl_ctx::maxnb_cnx, mihl_log(), MIHL_LOG_DEBUG, MIHL_LOG_ERROR, MIHL_LOG_INFO, MIHL_LOG_INFO_VERBOSE, MIHL_LOG_WARNING, mihl_ctx::nb_connexions, mihl_cnx::sockfd, mihl_cnxinfo_t::time_last_data, and mihl_cnxinfo_t::time_started.

Referenced by peek_key().

Here is the call graph for this function:

Here is the caller 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 migl_handle::filename, mihl_ctx::handles, mihl_ctx::log_level, mihl_log(), MIHL_LOG_DEBUG, MIHL_LOG_ERROR, MIHL_LOG_INFO, MIHL_LOG_INFO_VERBOSE, MIHL_LOG_WARNING, mihl_ctx::nb_connexions, mihl_ctx::nb_handles, migl_handle::pf_get, migl_handle::pf_post, and migl_handle::tag.

Referenced by peek_key().

Here is the call graph for this function:

Here is the caller 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_cnx::ctx, mihl_log(), MIHL_LOG_ERROR, MIN, read_file(), mihl_cnx::sockfd, and tcp_write().

Referenced by search_for_handle().

Here is the call graph for this function:

Here is the caller 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.

References mihl_cnx::authorization.

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.

References encodeblock().

Here is the call graph for this function:

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.

References decodeblock().

Here is the call graph for this function:


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.