libwebserver Functions
web_server_init()
NAME
web_server_init - Initialize webserver
SYNOPSIS
#include "web_server.h"
int web_server_init(struct web_server *server, int port, const char *logfile, int flags);
DESCRIPTION
The web_server_init() function initializes the server handler server, start a listen socket at port port, with the logfile logfile to produce the webserver log
if WS_USEEXTCONF flag is used, the logfile will be the config file
flags
WS_USESSL for openssl connections (https support)
WS_USEEXTCONF for using a external config file
WS_LOCAL only accepts 127.0.0.1 (local) connections
RETURN VALUE
On success, 1 is returned, On error, 0 is returned
web_server_addhandler()
NAME
web_server_addhandler - adds a request handler
SYNOPSIS
#include "web_server.h"
int web_server_addhandler(struct web_server *server, const char *mstr, void (*func)(), int flags);
DESCRIPTION
The web_server_addhandler() function adds a request handler mstr to the server handler server through the function func.
mstr is a string containing expressions (as matching files) to match with the client request (GET /blah.html?id=1 HTTP/1.0, will be matched by mstr="* /blah.html")
flags:
WS_LOCAL - only local connections are handled
WS_DYNVAR - treat dynamic variables on output (Atention: this disables "Content-range" and "Content-length" header, responding "501 not implemented")
WS_USELEN - With this flag, library calculate the header "Content-length" and "Content-range" it self, useful for resuming, content-length can be miscalculated if the file added by (web_client_addfile) changes the size of contents, between calculating and output
RETURN VALUE
On success, 1 is returned, On error, 0 is returned
web_server_run()
NAME
web_server_run - run the server
SYNOPSIS
#include "web_server.h"
int web_server_run(struct web_server *server);
DESCRIPTION
The web_server_run() function processes requests to the server server. This function must be called from the main application loop (the functions doesn't loop it self)
RETURN VALUE
On success, greater than 0, is returned (2 if there wasn't client, 1 if some request was processed), On error, 0 is returned
web_server_getconf()
NAME
web_server_getconf - get data from config filer
SYNOPSIS
#include "web_server.h"
char *web_server_getconf(struct web_server *server,char *topic,char *key);
DESCRIPTION
The web_server_getconf() function allocates and return a string from config file related to topic and key (see config file help) This function must be called after the init of the var server
RETURN VALUE
returns allocated string, (you should free after use) or null if nothing related to arguments found
web_server_useSSLcert()
NAME
web_server_useSSLcert - use certificate
SYNOPSIS
#include "web_server.h"
void web_server_useSSLcert(struct web_server *server, const char *file);
DESCRIPTION
The web_server_useSSLcert() function tells server server to use certificate file file on ssl connections (initializated w/ flag WS_USESSL)
web_client_addstream()
NAME
web_client_addstream - add an output stream to the client struct on webserver
SYNOPSIS
#include "web_server.h"
int web_client_addstream(FILE *stream);
DESCRIPTION
The web_client_addstream() function adds the stream stream to the output stream list in the current client node
NOTE
The web_client_addstream() function can only be called from functions called by gethandlers registered by web_server_addhandler().
The web_client_addstream() function is obsolete and no longer in use on 0.3.4 versions, use web_client_addfile instead
RETURN VALUE
On success, 1 is returned, On error, 0 is returned
web_client_addfile()
NAME
web_client_addfile - add a file to the output stream of the client struct on the webserver
SYNOPSIS
#include "web_server.h"
int web_client_addfile(const char *file);
DESCRIPTION
The web_client_addfile() function opens the file file and adds it as stream to the output stream list in the current client node
NOTE
The web_client_addfile() function can be called only from functions called by gethandlers registered via web_server_addhandler().
RETURN VALUE
On Success, 1 is returned, On error, 0 is returned
web_client_outputgif()
NAME
web_client_outputgif - export data as gif
SYNOPSIS
#include "web_server.h"
int web_client_outputgif(char *data,int w,int h);
DESCRIPTION
The web_client_outputgif() function prints to stdout a gif header (with width w and height h) and the image pointed by data.
The allocated memory data points to mustn't be smaller than w*h
NOTE
The web_client_outputgif() function can be called only from functions called by gethandlers registered via web_server_addhandler().
RETURN VALUE
On Success, 0 is returned, On error, non zero is returned.
web_client_setcookie()
NAME
web_client_setcookie - set a cookie
SYNOPSIS
#include "web_server.h"
void web_client_setcookie(char *key, char *value, char *timeoffset, char *path,char *domain,int secure);
DESCRIPTION
The web_client_setcookie() function sets a cookie on client browser with key key, value value and expires at timeoffset.
timeoffset format is one like sign, number offset and directive (i.e +10m, 10 months)
sign is on like '-' or '+'
number offset is like +5M means expires at next 5 minutes
path - Subset of URLs in a domain for which the cookie is valid
(If the path is not specified (path == NULL), it as assumed to be
the same path as the document being described by the header which
contains the cookie.)
domain = Domain the cookie is valid for
(If the domain is not set (domain == NULL), the default value of
domain is the host name of the server which generated the cookie
response.)
secure = If a cookie is marked secure (secure == 1), it will only be
transmitted if the communications channel with the host is a
secure one. Currently this means that secure cookies will only be
sent to HTTPS (HTTP over SSL) servers.
(If secure is not specified (secure == 0), a cookie is considered
safe to be sent in the clear over unsecured channels. )
NOTE
The web_client_setcookie() function should be called only from functions called by gethandlers registered via web_server_addhandler()
web_client_deletecookie()
NAME
web_client_deletecookie - delete a cookie
SYNOPSIS
#include "web_server.h"
void web_client_deletecookie(char *key);
DESCRIPTION
The web_client_deletecookie() function delete a cookie on client browser with key key
NOTE
The web_client_deletecookie() function should be called only from functions called by gethandlers registered via web_server_addhandler()
web_client_setvar()
NAME
web_client_setvar - sets a variable
SYNOPSIS
#include "web_server.h"
int web_client_setvar(char *name, char *value);
DESCRIPTION
The web_client_setvar() function sets an variable named name with value value in a connection, to be used in output (only available if WS_DYNVAR flag used)
web_client_setvar("bgc","#ff00dd");
printf("<BODY bgcolor='$bgc;'>"); - will exchange the string $bgc; to #ff00dd on output
NOTE
The web_client_setvar() function should be called only from functions called by gethandlers registered via web_server_addhandler().
web_client_getvar()
NAME
web_client_getvar - gets a variable value
SYNOPSIS
#include "web_server.h"
int web_client_getvar(char *name);
DESCRIPTION
The web_client_getvar() function gets the value of variable name, (see also web_client_setvar())
NOTE
The web_client_getvar() function should be called only from functions called by gethandlers registered via web_server_addhandler().
web_client_delvar()
NAME
web_client_delvar - delete a variable
SYNOPSIS
#include "web_server.h"
int web_client_delvar(char *name);
DESCRIPTION
The web_client_delvar() function deletes a variable with name name
NOTE
The web_client_delvar() function should be called only from functions called by gethandlers registered via web_server_addhandler().
web_client_HTTPdirective()
NAME
web_client_HTTPdirective - Change the HTTP header status
SYNOPSIS
#include "web_server.h"
void web_client_HTTPdirective(char *directive);
DESCRIPTION
The web_client_HTTPdirective() function changes the HTTP header status (i.e. "HTTP/1.1 200 OK") to the string directive
useful for "HTTP/1.1 401 Authorization Required" (to require a password), redirection or similar actions on the client side.
NOTE
The web_client_HTTPdirective() function can be called only from functions called by gethandlers registered via web_server_addhandler().
web_log()
NAME
web_log - write to logfile
SYNOPSIS
#include "web_server.h"
void web_log(const char *format,...);
DESCRIPTION
The web_log() is similar to printf, but writes to a logfile (specified in web_server_init()). Just as printf, it doesn't add a newline at the end.
NOTE
The web_log() function should be called only from functions called by gethandlers registered via web_server_addhandler().
ClientInfo
NAME
ClientInfo - a struct to control client Header
SYNOPSIS
Declared in web_server.h
extern struct ClientInfo {
int outfd;
char *inetname;
char *request;
char *method;
char *user;
char *pass;
char *(*Header)(char *handle);
char *(*Query)(char *handle);
char *(*Post)(char *handle);
char *(*Cookie)(char *handle);
char *(*Conf)(char *handle);
struct _MultiPart (*MultiPart)(char *handle);
void *__pad[5];
} *ClientInfo;
DESCRIPTION
ClientInfo->outfd is the filedescriptor of the current output stream (useful for cgi handlers and friends).
ClientInfo->inetname a string to inetname (i.e. "127.0.0.1")
ClientInfo->request is the requested 'file' (i.e. for "GET /index.html HTTP/1.0\r\n" the ClientInfo->request is "index.html")
ClientInfo->method is the request method ("GET" or "POST" etc..)
ClientInfo->user
ClientInfo->pass
ClientInfo->Header(char *handle) Function to parse the header, and returns Header information (i.e. for "Host: http://127.0.0.1:81" the result of ClientInfo->Header("Host") is "http://127.0.0.1:81") if argument handle is NULL then this function returns whole Header from client
ClientInfo->Query(char *handle) A function that returns the query value from the browser (i.e for the request "http://somehost.net/req.html?id=5&f=1", ClientInfo->Query("id") is "5".if argument handle is NULL then this function returns whole Query string from client
if the handle have the char # first (like "#handle") it returns the number of variables (usefull for checkboxes and etc...) Check checkbox example
ClientInfo->Post(char *handle) A function that returns the Post data from the forms with method 'POST'. handle is the name of some <input> tag.if argument handle is NULL then this function returns whole Post data from client
if the handle have the char # first (like "#handle") it returns the number of variables (usefull for checkboxes and etc...) Check checkbox example
ClientInfo->Cookie(char *handle) A function that returns the Cookie data from browser. if argument handle is NULL then this function returns whole Cookiestring from client
ClientInfo->Conf(char * topic,char *handle) A function that returns an value from a key in topic in the config file if used
ClientInfo->MultiPart(char *handle) A function that returns a data structure from the forms with method 'POST' and enctype='multipart/form-data' (useful for uploading files). handle is the name of some <input> tag.
the structure is
struct _MultiPart {
char *id;
char *data;
unsigned int size;
char *filename;
void *pad;
};
to be used as ClientInfo->MultiPart("file1").data; ClientInfo->MultiPart("file1").size; ClientInfo->MultiPart("file1").filename;
The config file
the config file is used as
[TOPIC]
KEY=VALUE
libwebserver configurations must be in topic LIBWEBSERVER as:
[LIBWEBSERVER]
LOG=help.log
PORT=80
USESSL=1
CERTFILE=foocert.pm
LOCAL=1
LOG -> the log file
PORT -> the listen port that will be used for tcp connections
USESSL -> the ssl flag if you want to use openssl for secure server (https)
CERTFILE -> the file that contains certificate for ssl connections
LOCAL -> only accept connections from 127.0.0.1