aboutsummaryrefslogtreecommitdiff
path: root/doc/functions.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/functions.html')
-rw-r--r--doc/functions.html355
1 files changed, 355 insertions, 0 deletions
diff --git a/doc/functions.html b/doc/functions.html
new file mode 100644
index 00000000..e28329ca
--- /dev/null
+++ b/doc/functions.html
@@ -0,0 +1,355 @@
1<center><H3><font color='007700'>libwebserver Functions</font></H3></center><BR><BR>
2<font face='Verdana'>
3
4<A name=web_server_init><B><font color='000077'>web_server_init()</font></B><BR><BR>
5<B>NAME</B>
6<UL>web_server_init - Initialize webserver</UL>
7<B>SYNOPSIS</B>
8<UL>#include "web_server.h"<BR><BR>int web_server_init(struct web_server *<U>server</U>, int <U>port</U>, const char *<U>logfile</U>, int <U>flags</U>);</UL>
9<B>DESCRIPTION</B>
10<UL>The web_server_init() function initializes the server handler <U>server</U>, start a listen socket at port <U>port</U>, with the logfile <U>logfile</U> to produce the webserver log<BR> if WS_USEEXTCONF flag is used, the <U>logfile</U> will be the config file <BR>
11<U>flags</U> <BR>
12WS_USESSL for openssl connections (https support)<BR>
13WS_USEEXTCONF for using a external config file<BR>
14WS_LOCAL only accepts 127.0.0.1 (local) connections
15</UL>
16
17<B>RETURN VALUE</B>
18<UL>On success, 1 is returned, On error, 0 is returned</UL>
19<HR><BR>
20
21
22<A name=web_server_addhandler><B><font color='000077'>web_server_addhandler()</font></B><BR><BR>
23<B>NAME</B>
24<UL>web_server_addhandler - adds a request handler</UL>
25<B>SYNOPSIS</B>
26<UL>#include "web_server.h"<BR><BR>int web_server_addhandler(struct web_server *<U>server</U>, const char *<U>mstr</U>, void (*<U>func</U>)(), int <U>flags</U>);</UL>
27<B>DESCRIPTION</B>
28<UL>The web_server_addhandler() function adds a request handler <U>mstr</U> to the server handler <U>server</U> through the function <U>func</U>.<BR>
29<U>mstr</U> is a string containing expressions (as matching files) to match with the client request (GET /<B>blah.html</B>?id=1 HTTP/1.0, will be matched by <U>mstr</U>="* /blah.html")<BR>
30<U>flags:</U> <BR>
31WS_LOCAL - only local connections are handled<BR>
32WS_DYNVAR - treat dynamic variables on output (Atention: this disables "Content-range" and "Content-length" header, responding "501 not implemented")<BR>
33WS_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<BR>
34</UL>
35<B>RETURN VALUE</B>
36<UL>On success, 1 is returned, On error, 0 is returned</UL>
37<HR><BR>
38
39<A name=web_server_aliasdir><B><font color='000077'>web_server_aliasdir()</font></B><BR><BR>
40<B>NAME</B>
41<UL>web_server_aliasdir - Generates a directory list, and use file based server</UL>
42<B>SYNOPSIS</B>
43<UL>#include "web_server.h"<BR><BR>int web_server_aliasdir(struct web_server *<U>server</U>, const char *<U>alias</U>, char *<U>path</U>, int <U>flags</U>);</UL>
44<B>DESCRIPTION</B>
45<UL>The web_server_aliasdir() function adds an alias <U>alias</U> to the server handler <U>server</U> and use files from <U>path</U>.<BR>
46<U>flags:</U> <BR>
47WS_LOCAL - only local connections are handled<BR>
48WS_DYNVAR - treat dynamic variables on output (Atention: this disables "Content-range" and "Content-length" header, responding "501 not implemented")<BR>
49WS_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<BR>
50</UL>
51<B>RETURN VALUE</B>
52<UL>On success, 1 is returned, On error, 0 is returned</UL>
53<HR><BR>
54
55<A name=web_server_run><B><font color='000077'>web_server_run()</font></B><BR><BR>
56<B>NAME</B>
57<UL>web_server_run - run the server</UL>
58<B>SYNOPSIS</B>
59<UL>#include "web_server.h"<BR><BR>int web_server_run(struct web_server *<U>server</U>);</UL>
60<B>DESCRIPTION</B>
61<UL>The web_server_run() function processes requests to the server <U>server</U>. This function must be called from the main application loop (the functions doesn't loop it self)</UL>
62<B>RETURN VALUE</B>
63<UL>On success, greater than 0, is returned (2 if there wasn't client, 1 if some request was processed), On error, 0 is returned</UL>
64<HR><BR>
65
66<A name=web_server_getconf><B><font color='000077'>web_server_getconf()</font></B><BR><BR>
67<B>NAME</B>
68<UL>web_server_getconf - get data from config filer</UL>
69<B>SYNOPSIS</B>
70<UL>#include "web_server.h"<BR><BR>char *web_server_getconf(struct web_server *<U>server</U>,char *<U>topic</U>,char *<U>key</U>);</UL>
71<B>DESCRIPTION</B>
72<UL>The web_server_getconf() function allocates and return a string from config file related to <U>topic</U> and <U>key</U> (see <a href="/?help=functions#configfile">config file help</a>) This function must be called after the init of the var <U>server</U></UL>
73<B>RETURN VALUE</B>
74<UL>returns allocated string, (you should free after use) or null if nothing related to arguments found</UL>
75<HR><BR>
76
77<A name=web_server_useSSLcert><B><font color='000077'>web_server_useSSLcert()</font></B><BR><BR>
78<B>NAME</B>
79<UL>web_server_useSSLcert - use certificate</UL>
80<B>SYNOPSIS</B>
81<UL>#include "web_server.h"<BR><BR>void web_server_useSSLcert(struct web_server *<U>server</U>, const char *<U>file</U>);</UL>
82<B>DESCRIPTION</B>
83<UL>The web_server_useSSLcert() function tells server <U>server</U> to use certificate file <U>file</U> on ssl connections (initializated w/ flag WS_USESSL)</UL>
84<HR><BR>
85
86<A name=web_server_useMIMEfile><B><font color='000077'>web_server_useMIMEfile()</font></B><BR><BR>
87<B>NAME</B>
88<UL>web_server_useMIMEfile - use mime types file</UL>
89<B>SYNOPSIS</B>
90<UL>#include "web_server.h"<BR><BR>void web_server_useMIMEfile(struct web_server *<U>server</U>, const char *<U>file</U>);</UL>
91<B>DESCRIPTION</B>
92<UL>The web_server_useMIMEfile() function tells server <U>server</U> to use mimes type file <U>file</U> for determining mime type by extension used by function <a href="/?help=functions#web_client_contenttype">web_client_contenttype()</a></UL>
93<HR><BR>
94
95
96<A name=web_client_addstream><B><font color='000077'>web_client_addstream()</font></B><BR><BR>
97<B>NAME</B>
98<UL>web_client_addstream - add an output stream to the client struct on webserver</UL>
99<B>SYNOPSIS</B>
100<UL>#include "web_server.h"<BR><BR>int web_client_addstream(FILE *<U>stream</U>);</UL>
101<B>DESCRIPTION</B>
102<UL>The web_client_addstream() function adds the stream <U>stream</U> to the output stream list in the current client node</UL>
103 <B>NOTE</B>
104<UL>The web_client_addstream() function can <B>only</B> be called from functions called by gethandlers registered by <a href='/?help=functions#web_server_addhandler'>web_server_addhandler()</a>.</UL>
105<UL>The web_client_addstream() function is obsolete and no longer in use on 0.3.4 versions, use web_client_addfile instead</ul>
106<B>RETURN VALUE</B>
107<UL>On success, 1 is returned, On error, 0 is returned</UL>
108<HR><BR>
109
110<A name=web_client_addfile><B><font color='000077'>web_client_addfile()</font></B><BR><BR>
111<B>NAME</B>
112<UL>web_client_addfile - add a file to the output stream of the client struct on the webserver</UL>
113<B>SYNOPSIS</B>
114<UL>#include "web_server.h"<BR><BR>int web_client_addfile(const char *<U>file</U>);</UL>
115<B>DESCRIPTION</B>
116<UL>The web_client_addfile() function opens the file <U>file</U> and adds it as stream to the output stream list in the current client node</UL>
117 <B>NOTE</B>
118<UL>The web_client_addfile() function can be called <B>only</B> from functions called by gethandlers registered via <a href='/?help=functions#web_server_addhandler'>web_server_addhandler()</a>.</UL>
119<B>RETURN VALUE</B>
120<UL>On Success, 1 is returned, On error, 0 is returned</UL>
121<HR><BR>
122
123<A name=web_client_gifoutput><B><font color='000077'>web_client_gifoutput()</font></B><BR><BR>
124<B>NAME</B>
125<UL>web_client_gifoutput - export data as gif</UL>
126<B>SYNOPSIS</B>
127<UL>#include "web_server.h"<BR><BR>int web_client_gifoutput(char *<U>data</U>,int <U>w</U>,int <U>h</u>);</UL>
128<B>DESCRIPTION</B>
129<UL>The web_client_gifoutput() function prints to stdout a gif header (with width <U>w</U> and height <U>h</U>) and the image pointed by <U>data</U>.<BR>
130The allocated memory <U>data</U> points to mustn't be smaller than <U>w</U>*<U>h</U>.<BR>
131The gif palette is described by <a href='/?help=functions#web_client_gifsetpalette'>web_client_gifsetpalette</a>
132</UL>
133<B>NOTE</B>
134<UL>The web_client_gifoutput() function can be called <B>only</B> from functions called by gethandlers registered via <a href='/?help=functions#web_server_addhandler'>web_server_addhandler()</a>.</UL>
135<B>RETURN VALUE</B>
136<UL>On Success, 0 is returned, On error, non zero is returned.</UL>
137<HR><BR>
138
139<A name=web_client_gifsetpalette><B><font color='000077'>web_client_gifsetpalette()</font></B><BR><BR>
140<B>NAME</B>
141<UL>web_client_gifsetpalette - Setup the gif palette</UL>
142<B>SYNOPSIS</B>
143<UL>#include "web_server.h"<BR><BR>void web_client_gifsetpalette(char *<U>file</U>);</UL>
144<B>DESCRIPTION</B>
145<UL>The web_client_gifsetpalette() function loads raw palette (.act) from <U>file</U> or if <U>file</U> is "EGA" then this function setups the palette to EGA mode<BR>
146</UL>
147<HR><BR>
148
149
150<A name=web_client_setcookie><B><font color='000077'>web_client_setcookie()</font></B><BR><BR>
151<B>NAME</B>
152<UL>web_client_setcookie - set a cookie</UL>
153<B>SYNOPSIS</B>
154<UL>#include "web_server.h"<BR><BR>void web_client_setcookie(char *<U>key</U>, char *<U>value</U>, char *<U>timeoffset</U>, char *<U>path</U>,char *<U>domain</U>,int <U>secure</U>);</UL>
155<B>DESCRIPTION</B>
156<UL>The web_client_setcookie() function sets a cookie on client browser with key <U>key</U>, value <U>value</U> and expires at <U>timeoffset</U>.<BR>
157timeoffset format is one like <U>sign</U>, <U>number offset</U> and <U>directive</U> <small> (i.e +10m, 10 months)</small>
158 <UL><U>sign</U> is on like '-' or '+'</UL>
159 <UL><U>number offset</U> is like +<U>5</U>M means expires at next 5 minutes </UL>
160 <UL><U>directive</U> is:
161 <UL>S - seconds</UL>
162 <UL>M - minutes</UL>
163 <UL>H - hours</UL>
164 <UL>d - days</UL>
165 <UL>m - months</UL>
166 <UL>y - years</UL>
167 </UL>
168 path - Subset of URLs in a domain for which the cookie is valid
169 (If the path is not specified (path == NULL), it as assumed to be
170 the same path as the document being described by the header which
171 contains the cookie.)<BR>
172 domain = Domain the cookie is valid for
173 (If the domain is not set (domain == NULL), the default value of
174 domain is the host name of the server which generated the cookie
175 response.)<BR>
176 secure = If a cookie is marked secure (secure == 1), it will only be
177 transmitted if the communications channel with the host is a
178 secure one. Currently this means that secure cookies will only be
179 sent to HTTPS (HTTP over SSL) servers.
180 (If secure is not specified (secure == 0), a cookie is considered
181 safe to be sent in the clear over unsecured channels. )<BR>
182
183</UL>
184<B>NOTE</B>
185<UL> The web_client_setcookie() function should be called <B>only</B> from functions called by gethandlers registered via <a href='/?help=functions#web_server_addhandler'>web_server_addhandler()</a><BR></UL>
186<HR><BR>
187
188
189<A name=web_client_deletecookie><B><font color='000077'>web_client_deletecookie()</font></B><BR><BR>
190<B>NAME</B>
191<UL>web_client_deletecookie - delete a cookie</UL>
192<B>SYNOPSIS</B>
193<UL>#include "web_server.h"<BR><BR>void web_client_deletecookie(char *<U>key</U>);</UL>
194<B>DESCRIPTION</B>
195<UL>The web_client_deletecookie() function delete a cookie on client browser with key <U>key</U><BR>
196
197</UL>
198<B>NOTE</B>
199<UL> The web_client_deletecookie() function should be called <B>only</B> from functions called by gethandlers registered via <a href='/?help=functions#web_server_addhandler'>web_server_addhandler()</a><BR></UL>
200<HR><BR>
201
202<A name=web_client_setvar><B><font color='000077'>web_client_setvar()</font></B><BR><BR>
203<B>NAME</B>
204<UL>web_client_setvar - sets a variable</UL>
205<B>SYNOPSIS</B>
206<UL>#include "web_server.h"<BR><BR>int web_client_setvar(char *<U>name</U>, char *<U>value</U>);</UL>
207<B>DESCRIPTION</B>
208<UL>The web_client_setvar() function sets an variable named <U>name</U> with value <U>value</U> in a connection, to be used in output (only available if WS_DYNVAR flag used)<BR>
209 web_client_setvar("bgc","#ff00dd");<BR>
210 printf("&lt;BODY bgcolor='$bgc;'&gt;"); - will exchange the string $bgc; to #ff00dd on output</UL>
211
212<B>NOTE</B>
213<UL>The web_client_setvar() function <B>should</B> be called <B>only</B> from functions called by gethandlers registered via <a href='/?help=functions#web_server_addhandler'>web_server_addhandler()</a>.</UL>
214<HR><BR>
215
216<A name=web_client_getvar><B><font color='000077'>web_client_getvar()</font></B><BR><BR>
217<B>NAME</B>
218<UL>web_client_getvar - gets a variable value</UL>
219<B>SYNOPSIS</B>
220<UL>#include "web_server.h"<BR><BR>int web_client_getvar(char *<U>name</U>);</UL>
221<B>DESCRIPTION</B>
222<UL>The web_client_getvar() function gets the value of variable <U>name</U>, (see also <a href=/?help=functions#web_client_setvar>web_client_setvar()</a>)<BR></UL>
223<B>NOTE</B>
224<UL>The web_client_getvar() function <B>should</B> be called <B>only</B> from functions called by gethandlers registered via <a href='/?help=functions#web_server_addhandler'>web_server_addhandler()</a>.</UL>
225<HR><BR>
226
227<A name=web_client_delvar><B><font color='000077'>web_client_delvar()</font></B><BR><BR>
228<B>NAME</B>
229<UL>web_client_delvar - delete a variable</UL>
230<B>SYNOPSIS</B>
231<UL>#include "web_server.h"<BR><BR>int web_client_delvar(char *<U>name</U>);</UL>
232<B>DESCRIPTION</B>
233<UL>The web_client_delvar() function deletes a variable with name <U>name</U><BR></UL>
234<B>NOTE</B>
235<UL>The web_client_delvar() function <B>should</B> be called <B>only</B> from functions called by gethandlers registered via <a href='/?help=functions#web_server_addhandler'>web_server_addhandler()</a>.</UL>
236<HR><BR>
237
238
239<A name=web_client_HTTPdirective><B><font color='000077'>web_client_HTTPdirective()</font></B><BR><BR>
240<B>NAME</B>
241<UL>web_client_HTTPdirective - Change the HTTP header status</UL>
242<B>SYNOPSIS</B>
243<UL>#include "web_server.h"<BR><BR>void web_client_HTTPdirective(char *<U>directive</U>);</UL>
244<B>DESCRIPTION</B>
245<UL>The web_client_HTTPdirective() function changes the HTTP header status (i.e. "HTTP/1.1 200 OK") to the string <U>directive</U><BR>
246<small><i>useful for "HTTP/1.1 401 Authorization Required" (to require a password), redirection or similar actions on the client side</i></small>.</UL>
247 <B>NOTE</B>
248<UL>The web_client_HTTPdirective() function can be called <B>only</B> from functions called by gethandlers registered via <a href='/?help=functions#web_server_addhandler'>web_server_addhandler()</a>.</UL>
249<HR><BR>
250
251<A name=web_client_contenttype><B><font color='000077'>web_client_contenttype()</font></B><BR><BR>
252<B>NAME</B>
253<UL>web_client_contenttype - prints to stdout the header "Content-type: */*"</UL>
254<B>SYNOPSIS</B>
255<UL>#include "web_server.h"<BR><BR>void web_client_contenttype(char *<U>extension</U>);</UL>
256<B>DESCRIPTION</B>
257<UL>The web_client_contenttype() prints to stdout the header "Content-type: */*", where '*/*' is determined by <U>extension</U> (i.e. "html" based on mimefile produces "Content-type: text/html\r\n\r\n" and "jpg" produces "Content-type: image/jpeg\r\n\r\n")<BR>
258<small>this function is used on <a href="/?help=functions#web_server_aliasdir">web_server_aliasdir()</a></small></UL>
259 <B>NOTE</B>
260<UL>This function uses mime types loaded at <a href="/?help=functions#web_server_useMIMEfile">web_server_useMIMEfile()</a> else it will print only "Content-type: text/plain\r\n\r\n"</UL>
261<HR><BR>
262
263<A name=web_log><B><font color='000077'>web_log()</font></B><BR><BR>
264<B>NAME</B>
265<UL>web_log - write to logfile</UL>
266<B>SYNOPSIS</B>
267<UL>#include "web_server.h"<BR><BR>void web_log(const char *<U>format</U>,<U>...</U>);</UL>
268<B>DESCRIPTION</B>
269<UL>The web_log() is similar to printf, but writes to a logfile (specified in <a href=/?help=functions#web_server_init>web_server_init()</a>). Just as printf, it doesn't add a newline at the end.</UL>
270 <B>NOTE</B>
271<UL>The web_log() function <B>should</B> be called <B>only</B> from functions called by gethandlers registered via <a href='/?help=functions#web_server_addhandler'>web_server_addhandler()</a>.</UL>
272<HR><BR>
273
274<A name=ClientInfo><B><font color='000077'>ClientInfo</font></B><BR><BR>
275<B>NAME</B>
276<UL>ClientInfo - a struct to control client Header</UL>
277<B>SYNOPSIS</B>
278<UL> Declared in web_server.h <BR><BR>
279extern struct ClientInfo {<BR>
280<UL>
281 int <U>outfd</U>;<BR>
282 char *<U>inetname</U>;<BR>
283 char *<U>request</U>;<BR>
284 char *<U>method</U>;<BR>
285 char *<U>user</U>;<BR>
286 char *<U>pass</U>;<BR>
287 char *(*<U>Header</U>)(char *handle);<BR>
288 char *(*<U>Query</U>)(char *handle);<BR>
289 char *(*<U>Post</U>)(char *handle);<BR>
290 char *(*<U>Cookie</U>)(char *handle);<BR>
291 char *(*<U>Conf</U>)(char *handle);<BR>
292 struct _MultiPart (*<U>MultiPart</U>)(char *handle);<BR>
293 void *__pad[5];<BR>
294</UL>
295} *<U>ClientInfo</U>;
296</UL>
297<B>DESCRIPTION</B>
298<UL>
299<B>ClientInfo-&gt;<U>outfd</U></B> <UL>is the filedescriptor of the current output stream (useful for cgi handlers and friends).</UL><BR>
300<B>ClientInfo-&gt;<U>inetname</U></B> <UL>a string to inetname (i.e. "127.0.0.1")</UL> <BR>
301<B>ClientInfo-&gt;<U>request</U></B> <UL>is the requested 'file' (i.e. for "GET /index.html HTTP/1.0\r\n" the ClientInfo-&gt;request is "/index.html")</UL><BR>
302<B>ClientInfo-&gt;<U>method</U></B> <UL>is the request method ("GET" or "POST" etc..)</UL><BR>
303<B>ClientInfo-&gt;<U>user</U></B> <UL>AuthRealm username</UL><BR>
304<B>ClientInfo-&gt;<U>pass</U></B> <UL>AuthRealm password</UL><BR>
305<B>ClientInfo-&gt;<U>Header(</U>char *<U>handle</U>)</B> <UL>Function to parse the header, and returns Header information (i.e. for "Host: http://127.0.0.1:81" the result of ClientInfo-&gt;Header("Host") is "http://127.0.0.1:81") if argument <U>handle</U> is NULL then this function returns whole Header from client</UL><BR>
306<B>ClientInfo-&gt;<U>Query(</U>char *<U>handle</U>)</B> <UL>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-&gt;Query("id") is "5".if argument <U>handle</U> is NULL then this function returns whole Query string from client<BR>if the handle have the char # first (like "#handle") it returns the number of variables (usefull for checkboxes and etc...) Check <a href='/?help=examples#checkbox'>checkbox example</a></UL><BR>
307<B>ClientInfo-&gt;<U>Post(</U>char *<U>handle</U>)</B> <UL>A function that returns the Post data from the forms with method 'POST'. <U>handle</U> is the name of some &lt;input&gt; tag.if argument <U>handle</U> is NULL then this function returns whole Post data from client<BR>if the handle have the char # first (like "#handle") it returns the number of variables (usefull for checkboxes and etc...) Check <a href='/?help=examples#checkbox'>checkbox example</a></UL><BR>
308<B>ClientInfo-&gt;<U>Cookie(</U>char *<U>handle</U>)</B> <UL>A function that returns the Cookie data from browser. if argument <U>handle</U> is NULL then this function returns whole Cookiestring from client</UL><BR>
309<B>ClientInfo-&gt;<U>Conf(</U>char * <U>topic</U>,char *<U>handle</U>)</B> <UL>A function that returns an value from a <U>key</U> in <U>topic</U> in the config file if used</UL><BR>
310<B>ClientInfo-&gt;<U>MultiPart(</U>char *<U>handle</U>)</B> <UL>A function that returns a data structure from the forms with method 'POST' and enctype='multipart/form-data' (useful for uploading files). <U>handle</U> is the name of some &lt;input&gt; tag.<BR><BR>
311the structure is<BR>
312struct _MultiPart {
313<UL>
314char *<U>id</u>;<BR>
315char *<U>data</U>;<BR>
316unsigned int <U>size</U>;<BR>
317char *<U>filename</U>;<BR>
318void *<U>pad</U>;<BR>
319</UL>
320};<BR>
321to be used as ClientInfo-&gt;<U>MultiPart</U>("file1").<U>data</U>; ClientInfo-&gt;<U>MultiPart</U>("file1").<U>size</U>; ClientInfo-&gt;<U>MultiPart</U>("file1").<U>filename</U>;
322</UL>
323
324</UL>
325<HR><BR>
326<A name=configfile><B><font color='000077'>The config file</font></B><BR><BR>
327<UL>the config file is used as<BR><BR>
328<PRE>
329[TOPIC]
330KEY=VALUE
331
332libwebserver configurations must be in topic LIBWEBSERVER as:
333[LIBWEBSERVER]
334LOG=help.log
335PORT=80
336USESSL=1
337CERTFILE=foocert.pm
338MIMEFILE=/etc/mime.types
339LOCAL=1
340
341LOG -> the log file
342PORT -> the listen port that will be used for tcp connections
343
344USESSL -> the ssl flag if you want to use openssl for secure server (https)
345CERTFILE -> the file that contains certificate for ssl connections
346MIMEFILE -> the file that contains mime.types similer to apache mimefile
347LOCAL -> only accept connections from 127.0.0.1
348
349</PRE>
350</UL>
351
352</font>
353
354
355