mihl.h File Reference


Detailed Description

HTTP embedded server library Copyright (C) 2006-2007 Olivier Singla http://mihl.sourceforge.net/.

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_tmihl_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_tmihl_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.


Enumeration Type Documentation

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_root(), http_root_post(), 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_root(), http_root_post(), 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.

Referenced by main().

Here is the caller graph for this function:

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:


Generated on Mon May 26 18:06:14 2008 for milh-example_2 by  doxygen 1.5.6