The HttpResMgr

The HTTP resource manager, or HttpResMgr for short, is a Web File Manager. The HttpResMgr was initially used in the FuguHub consumer product, but has now been replaced by a Lua version. The HttpResMgr is delivered as a free product for the Barracuda Embedded Web Server. The product can be used as is or be customized for various purposes. See the Web File Manager Readme file for an introduction to the HttpResMgr's capabilities.

The purpose of this tutorial is:

to give you an understanding of how to use the Virtual File System using C/C++ code;
to show you how the HttpResMgr works;
to introduce you to the client side resources required by the HttpResMgr -- i.e. JavaScript files, images, etc.

In short:

The HttpResMgr, which is implemented in C code, dynamically creates a HTML directory listing when navigating a file system. JavaScript code enhances the HttpResMgr's functionality and gives it capabilities such as searching, playing music, and a photo slide show. In addition to creating a HTML directory listing, the HttpResMgr can also generate a JSON directory listing. The JSON directory listing can be used by AJAX clients. For example, the searching is done by an AJAX implementation which recursively requests JSON directory listings from the server. The AJAX search implementation is explained in the AJAX example.

Despite its functionality, the HttpResMgr can easily fit in small embedded systems. You may, however, choose to remove all or some of the JavaScript enhancements such as the MP3 player.

The Web resource directory "WebResources\rtl" contains files used by the HttpResMgr. The Web File Manager client loads "WebResources\rtl\jquery.js" and the files in the "WebResources\rtl\wfm\" directory. The "\wfm\" directory contains the HttpResMgr's images, style sheet, and the JavaScript code -- i.e. the code that enhances the HttpResMgr. The "rtl" directory is not required, but minor changes to the HttpResMgr's C code is required if you do not include this directory.

Limitations in this example:

The Web File Manager shows a "Play All" button when visiting directories with MP3 files. The "Play All" button does not work in this example, however, the inline MP3 player works.

The Play All button requires the Lua enhanced HttpResMgr version, but this example does not include (activate) the LSP plugin.

The HttpResMgr is designed such that it can be enhanced by Lua code. The Lua file "WebResources\rtl\.lua\wfm.lua" implements the functionality needed by the "play all" button.

In Lua, a standard HttpResMgr is created by calling ba.create.resmgr(..) and the enhanced version is created by calling: ba.create.wfm(...)

The Lua object returned by ba.create.wfm(...) does the following when the Play All button is pressed: scans the directory, extracts the MP3 tags, and generates an XML file, which is sent to the client.

The third party media player, implemented in Flash, requires a license if used in a commercial application.

Getting Started

Compile and run the example. The example will not function if not run in obj\debug\
When the example is running, navigate to localhost:9357, and follow the presented tutorial.
Optionally read the rest of this documentation.

The Virtual File System (and C Code)

The Barracuda Virtual File System's (VFS) building blocks are the HttpDir and HttpPage classes. This example shows how to extend the default HttpDir implementation. The HttpResMgr extends the default HttpDir implementation.

The default implementation for HttpDir is to search for subdirectories in the VFS. The directory node delegates the request to the sub-node if the directory is found. This continues down into sub-nodes until a HttpPage is found or an extended HttpDir implementation traps the request. The HttpResMgr extends the HttpDir class and allows a client to manage files on, for example, a file system.

As an example, assume we have the following virtual directory structure:

server root dir | + dir1 + | + dir2 (HttpResMgr instance)

Let us assume that the server root directory and dir1 are standard HttpDir instances and that dir2 is a HttpResMgr instance. Assume a client sends the following URL: http://localhost/dir1/dir2/dir3/dir4/

server root dir Service function receives path 'dir1/dir2/dir3/dir4/' and finds dir1. | + dir1 + Service function receives path 'dir2/dir3/dir4/' and finds dir2. | + dir2 The HttpResMgr Service function receives path 'dir3/dir4/'.

The server parses the request and delegates the request to the first root directory.
The root directory strips of 'dir1' from the path and calls the service function in dir1.
dir1 strips of 'dir2' from the path and calls the service function in dir2.
The HttpResMgr service function searches the hard drive for 'dir3/dir4/' and returns a directory listing to the client if the directory is found.

The HttpResMgr does not know that it is working with a hard drive. The HttpResMgr is using functions in the IoIntf API when working with files. The HttpResMgr can work with anything that implements the IoIntf API, which can be a hard drive, a ZIP file, or, for example, a database.

For example, the path 'dir3/dir4/' can be:

The path 'dir3/dir4/' inside a ZIP file.
From the physical path 'c:\webserver\dir3\dir4'.
From table 'dir4' in the database file 'dir3'.

Assembling a Virtual Directory Structure

A standard Barracuda application assembles the VFS at startup. The examples assemble the file system in InstallVD.c or InstallVirtualDir.cpp for C++ applications.

As an example, you can create multiple HttpResMgr instances that are using the same IoIntf implementation. The same physical file can then be accessed from two different URL's. This example assembles a VFS that is using a HttpResRdr for read only access to files and a HttpResMgr for read and write access to files. The base url 'public' and 'private' point to the same resource on the hard drive.

How the HttpResMgr Works

The core of the HttpResMgr is the request service function. This function is called from the parent directory node when the parent directory node delegates the request to the HttpResMgr.

The HttpResMgr service function prototype:

int HttpResMgr_service(HttpDir* super, const char* relPath, HttpCommand* cmd);

An HttpDir service function is similar to an HttpPage service function, though an HttpPage is always a leaf node -- i.e., one resource. An HttpDir is a collection of one or several resources.

The relPath (relative path) argument is a relative path extracted from the client URL. From the above example, the path received is 'dir3/dir4/'

The service function extracts the client path/parameters/command and executes the request. Uploading data from the client to the server is per the HTTP specification, normally HTTP PUT. Browsers cannot use PUT, but can upload data using multipart POST if an HTML page contains a form with the enctype set to 'multipart/form-data'.

Some servers can be configured to accept multipart POST and upload files to a fixed location in the server's local storage by, for example, using a CGI script. The HttpResMgr class does not have this limitation. You can upload files to any subdirectory from the HttpResMgr's configured root directory. The HttpResMgr dynamically generates a HTML page as follows when the upload button is pressed in the file manager:

The rtl Resource Directory

The "WebResources\rtl" directory contains code that is required by the HttpResMgr. The HttpResMgr C code generates HTML that includes jquery.js, wfm.js, and style.css. You must modify the HttpResMgr and remove the code that emits HTML code for referencing these three files if you do not plan on using the enhancements. A style sheet can be generated inline in the produced HTML.

rtl/jquery.js:

jQuery makes it much easier to design Rich Internet Applications (RIA) and AJAX applications. The JavaScript code in the "RTL" directory is deeply dependent on this code. The jQuery JavaScript code included in the RTL directory is a concatenation of jQuery and two plugins. The mkJquery.sh script can generate a new version using the latest release.
rtl/wfm/wfm.js:

The JavaScript code in this file, which is included by the page generated by the HttpResMgr C code, enhances the HttpResMgr user interface.
rtl/wfm/mp3player.html:

The "play all" MP3 player is opened if the "play all" button is pressed. The MP3 player that opens when the "play all" button is pressed, does not work in this example since the example is not LSP enabled. The MP3 player requests a XML playlist from the Lua script: rtl/.lua/wfm.lua.

You can still play MP3 songs without this functionality. The embedded Web file Manager MP3 player does not require the wfm.lua script.
rtl/.lua/wfs.lua:

The Lua version of the Web file Manager embedded in the HttpResMgr class. See ba.create.wfs for more information.
rtl/wfm/mediaplayer.swf:

The third party Flash media player requires a license if used in a commercial application.
rtl/wfm/swfobject.js:

SWFObject is an easy-to-use and standards-friendly method to embed Flash content.
rtl/wfm/style.css:

The HttpResMgr style sheet.
rtl/wfm/clipboard.swf:

A Flash file that makes it possible for the Web File Manager to copy the current URL to the computer's clipboard.
rtl/wfm/clipboard.js:

Clipboard implementation activated by pressing the clipboard button. The JavaScript code bridges the Web File Manager and the Flash code in clipboard.swf.
rtl/wfm/search.html:

This HTML file includes the JavaScript code for recursively searching the file system by sending AJAX calls to the server. The HttpResMgr server returns the response as JSON.
rtl/wfm/SearchList.html:

The search list is included as an iframe in search.html.
rtl/wfm/album/:

The photo album implementation.