/** @mainpage


@n<h2>              SOFTWARE FOR EMBEDDED DEVICES  V1.2.1
</h2>


<h3>      Contents
</h3>
          1  Introduction
@n        2  Modules
@n        2.1  Embedded Filesystem
@n        2.2  Simple FTP demon
@n        2.3  Simple HTTP demon
@n        3  Demo Program
@n        4  License
@n        5  Contact Information
@n
@n
@n
<h3>      1  Introduction
</h3>
          This package contains two modules:

            -  A simple file system for embedded devices

            -  A simple but powerful FTP demon based on a standard
               BSD socket API and the embedded filesystem.

            -  A simple but powerful HTTP demon based on a standard
               BSD socket API and the embedded filesystem.

@n        I developed this software package because I needed a FTP
          demon to be able to do software updates via ethernet to my
          embedded device. To save resources, the FTPD does only use
          one single task, and no further synchronization methods are
          required. For the TCP/IP stack I plan to use lightweight IP
          (project homepage: http://savannah.nongnu.org/projects/lwip).
          First I thought it would be sufficient to be able to store
          only a single file in the device' memory, but then I recognized
          the power of a real file system even in the embedded environment.
          With my file system you will be able to run a real HTTP server
          with either static html pages you have uploaded via FTP or
          dynamic pages that were created and stored to a file at runtime.
@n
@n
@n
<h3>      2  Modules
</h3>
<h4>      2.1  Embedded Filesystem
</h4>
<tt>      Source files:  filesys.c, filesys.h, sys.h
</tt>
@n@n      The file system supports all usual methods, like opening / reading
          from / writing to a file, random accesses, renaming and deleting
          files, and searching for files to print directory listings.

          Here is a list of some of the ANSI conform functions that are
          supported:
    
<tt>        open, close, read, write, seek, tell, stat, findfirst, findnext
</tt>
@n@n      There is one small restriction: The file system does only support
          one physical directory. Sub-directories are not yet supported.
          But there is a bit 'cosmetic' implemented that simulates the
          presence of subdirectories. If the define FS_SUBDIRECTORIES is
          set to 1, some additional functions were exported to manage
          subdirectories, with knowledge that all files will still be
          stored in the root directory. Even when the filesystem behaves
          like it is capable of subdirectories, storing much files in the
          RAM drive will significantly decrease the file access time, since
          always all file entries must be searched.

          The file system has one powerful feature: It handles up to two
          disk images. A disk image can be stored in RAM and thus is
          writable, or it can be stored in ROM and is then marked read-only.
          The combination of this two images would result in a powerful
          environment for a HTTP server: static web pages and pictures
          can be stored in ROM, and some writeable memory is used to store
          dynamically generated pages. The HTTP server will only need to
          access one directory in the filesystem, where all the files are
          stored.

          The following steps must be performed to set up the file system:

            -   Call ::fsys_init (size, blocksize, maxFileNameLength).
                If 'size' is nonzero, a new RAM drive image is created
                with the given size (in bytes). 'blocksize' is the size
                of the smallest entity the filesystem can manage, and
                'maxFileNameLength' is the maximum allowed length a
                filename can have. You should set 'maxFileNameLength'
                to a bigger value if you wish to use simulated subdirectories.
                If 'size' is zero, the file system will be initialized but
                no memory is assigned to it. In this case, 'blocksize'
                and 'maxFileNameLength' are don't cares.

            -   Optional: call ::fsys_addDriveImage to add a writeable
                drive image to the file system if fsys_init was called with
                size = 0, and/or:

            -   Optional: call ::fsys_addDriveImage to add a non-writeable
                drive image to the file system. The image may reside in
                a flash ROM or EPROM.


@n
<h4>      2.2  Simple FTP demon
</h4>
<tt>      Source files:  ftpd.c, ftpd.h, sys.h
</tt>
@n@n      The FTP demon is socket based and single threaded. It allows
          multiple connections simultaneously. All necessary FTP commands
          for file up- and download are supported. But there is still
          a restriction: Only one username/password pair is supported
          (that means no rights-management is done).

          The following steps must be performed to start the FTP demon:

            -   Call ::ftpd_start (username, password).
                This will start the demon and allows a user to log in
                with its 'username' and 'password'.


@n
<h4>      2.3  Simple HTTP demon
</h4>
<tt>      Source files:  httpd.c, httpd.h, sys.h
</tt>
@n@n      The HTTP demon is socket based and single threaded. It allows
          multiple connections simultaneously. Currently the demon supports
          the HEAD and the GET method, which allows serving static and
          dynamic html pages. The http demon can be configured to support
          active content through a servlet mechanism (this is compareable to
          JAVA servlets, and works like cgi scripts).

          The HTTP demon is conditionally compliant to HTTP/1.1 (RFC 2616).

          The following steps must be performed to start the HTTP demon:

            -   Call the function ::httpd_start.
                This will configure and start the demon and allows http
                access to the directory given as parameter.

@n
@n
<h3>      3  Demo Programs
</h3>
          The program <tt> 'ftpdrive.exe' (ftpdrive.c) </tt> demonstrates the
          usage of the file system, FTPD and HTTPD. It allows to load previously
          saved images to RAM, to create new RAM drive images and to store
          changed images to disk. Thus the program can also be used as tool
          to create ROM-able drive images to be used in an embedded HTTP
          server environment. Also the HTTP demon is included in this tool,
          so the RAM drive can also be accessed through a web browser.
@n@n
          The program <tt> 'servletdemo.exe' (sldemo.c and other files) </tt>
          demonstrate how to use the servlet mechansim. This demo program
          serves several dynamic html pages. The sourcecode of the servlets
          can be found in the demo subdirecty, the files are named from
          servlet1.c to servlet5.c.
@n@n
          The program <tt> 'httpserv.exe' (httpserv.c) </tt> is a small
          HTTP webserver for MS Windows. The program does not use the
          embedded filesystem; instead it does direct file access to
          the Windows filesystem. It allows you to set a root path
          at startup (command line parameter). The root is the directory
          where the file index.html is stored.
@n@n
          To build the demo programs, simply type <tt> 'make all' </tt> at
          the command prompt. The demo programs were tested with the MinGW
          compiler running under Windows 98 SE.
@n
@n
@n
<h3>      4  License
</h3>
          Copyright (c) 2004, Dennis Kuschel.
@n        All rights reserved. 
@n
@n        Redistribution and use in source and binary forms, with or without
          modification, are permitted provided that the following conditions
          are met:
@n 
           -# Redistributions of source code must retain the above copyright
              notice, this list of conditions and the following disclaimer.
           -# Redistributions in binary form must reproduce the above copyright
              notice, this list of conditions and the following disclaimer in the
              documentation and/or other materials provided with the distribution.
           -# The name of the author may not be used to endorse or promote
              products derived from this software without specific prior written
              permission. 
 
          THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
          OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
          WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
          ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
          INDIRECT,  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
          (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
          SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
          HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
          STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
          ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
          OF THE POSSIBILITY OF SUCH DAMAGE.
@n
@n
@n
<h3>      5  Contact Information
</h3>
          Author:

          Dennis Kuschel  (dennis_k@freenet.de)
@n        http://mycpu.mikrocontroller.net
*/
