HttpResRdr Struct Reference

Detailed Description

The HTTP resource reader searches and presents IoIntf resources to HTTP clients requesting such information.

The HttpResRdr class makes it possible for HTTP clients to fetch resources from an IoIntf implementation. The HttpResRdr is a bridge between HTTP request/response and the IoIntf implementation. As an example, the HttpResRdr class can fetch files such as HTML files, GIF images, etc. from a file system and send the file to an HTTP client requesting the information.

The HttpResRdr can only download files to a client, not upload files to the server; thus, the HttpResRdr is only using the "read" methods in the IoIntf. HTTP Methods supported by HttpResRdr are: OPTIONS, GET, or HEAD. HttpResRdr accepts any HTTP method for include/forward delegations and files not found. This is explained below.

The HttpResRdr searches the IoIntf for the requested resource and automatically handles the response. If the resource cannot be found, HttpResRdr delegates the request to the original HttpDir service function. The HTTP Method type is ignored if the resource is not found. This means that you can insert CSP or HttpDir/HttpPage instances in the HttpResRdr by using HttpDir::insertPage and HttpDir::insertDir.

A client requesting a directory ending with '/' makes the HttpResRdr search for index.X files, where X is 'htm', 'html', and extensions as specified by installed filters. The HttpDir service method returns -1 if no index.X file can be found or the directory does not end with '/'.

The HttpResRdr treats files with extension 'shtml' as hidden files that can only be accessed via HttpResponse::forward or HttpResponse::include.

The HttpResRdr is specifically designed to be used with HttpResponse::include and HttpResponse::forward. The HTTP method is ignored and is assumed to be a GET if the HttpResRdr detects that this is a forward or include call. This makes it possible to design model view controller applications by using HttpResponse::forward from a CSP page or an HttpPage.

Response data is sent with an HTTP size header for direct delegations and HttpResponse::forward delegations. HttpResponse::include delegations require special handling and data is sent using chunk encoding for HTTP 1.1 clients.

The HttpResRdr sends weak, quoted ETags based on the full modification timestamp and file size, without reading the file. If-None-Match uses weak comparison and takes precedence over If-Modified-Since. If-Match uses strong comparison, so only its wildcard can match these weak ETags; it takes precedence over If-Unmodified-Since. Failed read conditions return 304 or 412 as appropriate. Invalid entity-tag syntax returns 400. WebDAV uses the same tags and comparisons for its file reads and writes. Same-size edits within the timestamp resolution can retain the same tag; applications requiring content revision tracking must supply their own validators. If-Range is not evaluated: its presence selects the full response.

Limitations:
A HttpResRdr instance is normally used for downloading small HTML files, gif images etc, but may also be used for downloading large files. The HttpResRdr instance blocks the current thread when downloading a file and a large file may take considerable time to download. A Barracuda Web-Server running in the default single threaded mode will block all other requests while downloading a large file. It is, therefore, recommended to run the server in multi threaded mode if you use a HttpResRdr instance to download large files. See class HttpCmdThreadPool for more information.

#include <HttpResRdr.h>

Inheritance diagram for HttpResRdr:

Public Member Functions
	HttpResRdr ()
	Uninitialized storage; call a C constructor before use. More...
	HttpResRdr (IoIntf *io, const char *dirName, AllocatorIntf *alloc=0, S8 priority=0)
	Initializes a HttpResRdr. More...
	HttpResRdr (IoIntf *io, const char *domain, const char *p404, AllocatorIntf *alloc=0, S8 priority=0)
	Initialize a HttpResRdr for name based virtual hosting. More...
int	insertPrologDir (HttpDir *dir)
	Insert a prologue HttpDir. More...
	~HttpResRdr ()
	Detach and destroy directory state, including the prologue root and owned custom-header storage. More...
int	installFilter (HttpRdFilter *filter)
	Install a file-extension filter. More...
void	setMaxAge (BaTime maxAge)
	Configure Cache-Control max-age for ordinary static resources. More...
IoIntf *	getIo ()
	Access the filesystem supplied at construction. More...
Public Member Functions inherited from HttpDir
	HttpDir ()
	Constructor for creating a root dir, a root dir has no name. More...
	HttpDir (const char *name, S8 priority=0)
	Constructor for creating a sub-directory. More...
	~HttpDir ()
	Unlink this directory and notify all child pages/directories through their service callbacks with NULL request arguments. More...
int	insertDir (HttpDir *dir)
	Insert a sub-directory. More...
int	insertPage (HttpPage *page)
	Insert a page in the directory. More...
HttpPage *	getFirstPage ()
	Returns the first page. More...
HttpDir *	getFirstDir ()
	Returns the first sub-directory. More...
HttpDir *	getDir (const char *name)
	Returns the first directory with the name given or NULL if not found. More...
HttpPage *	getPage (const char *name)
	Returns the page with the name given or NULL if not found. More...
HttpDir *	getNext ()
	Returns the next dir in the parent list. More...
HttpPage *	findPage (HttpPage *iter, const char *name)
	Searches for a page in this directory node. More...
HttpDir *	createOrGet (const char *name)
	Returns a sub-directory with the given name. More...
const char *	getName () const
	Returns the directory name. More...
HttpDir *	getParent () const
	Returns the parent directory or NULL if no parent. More...
char *	makeAbsPath (const char *relPath, int relPathLen)
	Makes an absolute path based on where the HttpDir instance is installed in the virtual file system and the provided relative path. More...
char *	getRootPath ()
	Calculates the root of where the HttpDir instance is installed in the virtual file system. More...
HttpDir_Service	setService (HttpDir_Service s)
	Replace the original service function in HttpDir with your own. More...
void	p403 (const char *p403)
	Set a 403 denied request handler. More...
bool	isLinked ()
	Returns true if this directory node is installed into a parent directory. More...
int	unlink ()
	Unlinks/removes the directory from the parent directory. More...
void	setAuthenticator (struct AuthenticatorIntf *authenticator, struct AuthorizerIntf *authorizer=0)
	Set the optional authenticator and optional AuthorizerIntf. More...
bool	authenticateAndAuthorize (HttpCommand *cmd, const char *path)
	Authenticate and authorize the user. More...

Static Public Member Functions
static void	sendFile (IoIntf *io, const char *name, IoStat *st, HttpCommand *cmd)
	Send an IoIntf resource through the current response. More...
Static Public Member Functions inherited from HttpDir
static HttpDir *	findDir (HttpDir *iter, const char *name, unsigned int nameLen)
	Searches for a sub-directory in this directory node. More...

Constructor & Destructor Documentation

HttpResRdr() [1/3]

HttpResRdr::HttpResRdr

(

)

Uninitialized storage; call a C constructor before use.

HttpResRdr() [2/3]

HttpResRdr::HttpResRdr	(	IoIntf *	io,
		const char *	dirName,
		AllocatorIntf *	alloc = 0,
		S8	priority = 0
	)

Initializes a HttpResRdr.

Parameters

io	Required borrowed IoIntf implementation, which must outlive the reader.
dirName	is the HttpDir name. You must allocate persistent memory for this string if not constant. See HttpDir for an example.
alloc	Borrowed allocator for temporary strings; NULL selects AllocatorIntf_getDefault(). Retain it until reader destruction.
priority	Signed 8-bit HttpDir priority; the default is zero.

HttpResRdr() [3/3]

HttpResRdr::HttpResRdr	(	IoIntf *	io,
		const char *	domain,
		const char *	p404,
		AllocatorIntf *	alloc = 0,
		S8	priority = 0
	)

Initialize a HttpResRdr for name based virtual hosting.

A HttpResRdr instance initialized for virtual hosting must be installed as a root directory using method HttpServer::insertRootDir.

The C constructor name is: HttpResRdr_constructor2.

Please note that you must allocate persistent memory for the string 'domain' and 'p404' if not constant. See HttpDir for an example.

Parameters

io	Required borrowed IoIntf implementation, which must outlive the reader.
domain	Required borrowed NUL-terminated domain. The current implementation compares it exactly with the parsed request domain.
p404	is the path to a 404 resource. The HttpResRdr instance automatically forwards the request to this resource if the resource requested for this domain was not found. You can set this parameter to NULL, thus making the web-server continue searching for the page in another resource with the same domain or in a resource that accepts any domain. The 404 resource can be a CSP page, an LSP page, a static HTML page, etc..
alloc	Borrowed allocator for temporary strings; NULL selects AllocatorIntf_getDefault(). Retain it until reader destruction.
priority	Signed 8-bit HttpDir priority; the default is zero.

~HttpResRdr()

HttpResRdr::~HttpResRdr

(

)

Detach and destroy directory state, including the prologue root and owned custom-header storage.

Filters are unlinked, not freed. Borrowed IoIntf, allocator, and configuration strings are not destroyed. Stop active users first; inherited HttpDir cleanup rules also apply.

Member Function Documentation

getIo()

IoIntf * HttpResRdr::getIo

(

)

Access the filesystem supplied at construction.

Returns

Non-NULL borrowed IoIntf pointer; ownership does not change.

insertPrologDir()

int HttpResRdr::insertPrologDir

(

HttpDir *

dir

)

Insert a prologue HttpDir.

prologue directories are activated (called) before the HttpResRdr service function is run, but after authentication. The HttpResRdr service function is not activated if a prologue directory finds the resource. Epilogue directories can be inserted by using method HttpDir::insertDir. prologue and epilogue directories are chained instead of added as subdirectories if the directory name for the added directories is NULL. The priorities for subdirectories and chained directories are: prologue > HttpResRdr > epilogue.

Parameters

dir	Required initialized directory, not already installed elsewhere. It remains subject to HttpDir ownership and destruction rules.

Returns

Zero on successful insertion, E_MALLOC if the prologue root cannot be allocated, or the error returned by HttpDir::insertDir.

installFilter()

int HttpResRdr::installFilter

(

HttpRdFilter *

filter

)

Install a file-extension filter.

Parameters

filter

Required initialized, currently unlinked filter. Borrowed until it is unlinked or the reader is destroyed; never installed in two readers.

Returns

Zero on success, -1 when that exact extension is already installed. Recognized built-in MIME types take precedence over filters for direct files. Filters also supply candidate index extensions after index.html/index.htm.

sendFile()

void HttpResRdr::sendFile ( IoIntf *  io, const char *  name, IoStat *  st, HttpCommand *  cmd  )

static

Send an IoIntf resource through the current response.

Parameters

io	Required borrowed filesystem containing name.
name	Required NUL-terminated path relative to io, valid during this call.
st	Required current metadata from a successful IoIntf::stat for name.
cmd	Required request/response container. For ordinary output, do not send body data or commit headers before calling. Includes use a separate internal streaming path; forwards are handled as resource output. Handles ordinary GET/HEAD/OPTIONS, caching, and supported range requests. No status is returned. I/O failures are handled through the response and can terminate the connection; already-sent bytes cannot be retracted.

setMaxAge()

void HttpResRdr::setMaxAge

(

BaTime

maxAge

)

Configure Cache-Control max-age for ordinary static resources.

Parameters

maxAge

Lifetime in seconds. Zero (default) disables this reader's automatic max-age header. Filter responses and includes do not receive this setting automatically. See HttpResponse::setMaxAge.