vxUtils Files

/*******************************************************************************
 *  Copyright (c) 2009, Arthur Benilov
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 ******************************************************************************/


This library contains a minimalistic implementation of HTTP 1.0 server
for VxWorks targets. Also it provides XML RPC (server) interface via HTTP.
 
Supported features:
-------------------
 
 - GET, PUT, or POST requests only.
 - CGI as C functions that can be mapped to URI.
 - Multithreading (each client connected is handled by a separate thread).
 - stdio output redirection for CGI functions (can use printf() to output directly
   to the client).
 - GET requests parameters string parsing.
 - Keep-alive connection.
 - XML RPC service (using ezxml parser, http://ezxml.sourceforge.net/).
 
Configuring:
------------
 
All configuration parameters are in httpd.h header file. None of these
parameters can be modified in runtime.
 
HTTPD_MAX_SESSIONS 
    Specified number of clients' session the server may create. Each session
    is a separate task (thread) that handles HTTP communication with a client.
    Move sessions you allow, more clients can connect to the server at the
    same time. If you use CGI function that may cause some delay, it's better
    to allow several sessions.
    
HTTPD_REQUEST_TIMEOUT
    Number of milliseconds the server waits for the request from a just connected
    client. If this time expires, the server drops connection (see HTTPD_KEEPALIVE_TIMEOUT
    for keep-alive connections).
    
HTTPD_KEEP_ALIVE_TIMEOUT
    Number of 'wait cycles' the server waits for the request from a client. If
    keep-alive option is enabled, the server will wait in total for
    HTTPD_KEEP_ALIVE_TIMEOUT * HTTPD_REQUEST_TIMEOUT milliseconds for the request
    from a client. When this time expires, the server drops connection.
    
HTTPD_STDIO_REDIRECT
    Once this parameters is defined, all output to the stdio of CGI functions
    will be automatically redirected to a client. This concerns only those functions
    called from HTTP session tasks. All other functions will continue to output
    to stdio. If you want your CGI function to output in stdio, you have to disable
    this option. In this case you may use httpd_printf() that acts like printf() function
    but outputs to a client's socket.
    
HTTPD_MAX_INPUT_BUFFER_SIZE
    Number of bytes the server may receive from a client as a HTTP request. Normally
    HTTP requests are quite short, so you may want to change this value in order to
    save some memory. If an incoming request is longer than this value, the server
    will drop connection with an error.
    
HTTPD_MAX_OUTPUT_BUFFER_SIZE
    Size of a buffer used by httpd_printf() function. If you use stdio redirection
    you should not care about adjusting this value. Elsewhere you may want to
    change it in order to same some memory (that is allocated from session task stack).
    
HTTPD_MAIN_PRIORITY
    HTTP main task priority. Main task accepts incoming connections and create session
    tasks.
    
HTTPD_SESSION_PRIORITY
    Session tasks priority
    
HTTPD_MAIN_STACK_SIZE
    Stack allocated for HTTP server main task. You do not need to change this value
    since CGI functions stack is allocated from sesstions tasks stack.
    
HTTPD_SESSION_STACK_SIZE
    Stack allocated for every session task. You may want to increase this value
    if your CGI function uses alot of local variables. Pay attantion to this
    elsewhere stack overflow may easily occured in while executing your CGI function.
    
HTTPD_ALLOW_FILES
    If this option is defined, the server may transfer files from local file system
    to a client (just like an ordinal web server).
    
HTTPD_DOC_ROOT
    If you allow file serving, this parameter should specify a location of files
    visible to a server
    
HTTPD_INDEX_FILE
    Name of a file the server will try to forward to a client in case when requested
    URL does not cantain explicitely a name of a file (like http://server/). By default
    it's 'index.html' If you have a CGI function that has been mapped on exactly the same
    file name, the server will execute a CGI function rather than forward a file.
    
Compiling and usage:
--------------------

There are no any special tricks for the server compiling. See example.c file containing
a source code using the provided HTTP server.

See example_xmlrpc.c file for XML RPC service activation and usage.

--------------------------------------------------------------------------------
2009, by Arthur Benilov (arthur.benilov@gmail.com)