HttpResRdr.h File Reference

#include "IoIntf.h"
#include "BaServerLib.h"
#include "HttpServer.h"

Include dependency graph for HttpResRdr.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	HttpRdFilter
	Superclass for HttpResRdr filters. More...
struct	HttpResRdr
	The HTTP resource reader searches and presents IoIntf resources to HTTP clients requesting such information. More...

Macros
#define	HttpResRdr_setMaxAge(o, maxAgeMA)   (o)->maxAge=maxAgeMA
	C form of HttpResRdr::setMaxAge. More...
#define	HttpResRdr_setAuthenticator(o, authenticator, realm)    HttpDir_setAuthenticator((HttpDir*)o, authenticator, realm)
	Configure inherited authentication and authorization. More...
#define	HttpResRdr_getIo(o)   (o)->io
	Access the filesystem supplied at construction. More...

Typedefs
typedef void(*	HttpRdFilter_Service) (struct HttpRdFilter *o, const char *name, IoStat *st, HttpCommand *cmd)
	Process a resource selected by a reader's file-extension filter. More...
typedef struct HttpRdFilter	HttpRdFilter
	Superclass for HttpResRdr filters. More...
typedef HttpResRdr	HttpResRdr
	The HTTP resource reader searches and presents IoIntf resources to HTTP clients requesting such information. More...

Functions
BA_API void	HttpRdFilter_constructor (HttpRdFilter *o, const char *ext, HttpRdFilter_Service serviceFp)
	Initialize a filter without installing it. More...
BA_API void	HttpRdFilter_destructor (HttpRdFilter *o)
	Unlink a filter from its reader if installed. More...
BA_API void	HttpResRdr_constructor (HttpResRdr *o, IoIntf *io, const char *dirName, AllocatorIntf *alloc, S8 priority)
	Initializes a HttpResRdr. More...
BA_API void	HttpResRdr_constructor2 (HttpResRdr *o, IoIntf *io, const char *domain, const char *p404, AllocatorIntf *alloc, S8 priority)
	Initialize a HttpResRdr for name based virtual hosting. More...
BA_API int	HttpResRdr_insertPrologDir (HttpResRdr *o, HttpDir *dir)
	Insert a prologue HttpDir. More...
BA_API void	HttpResRdr_destructor (HttpResRdr *o)
	Detach and destroy directory state, including the prologue root and owned custom-header storage. More...
BA_API int	HttpResRdr_installFilter (HttpResRdr *o, HttpRdFilter *filter)
	Install a file-extension filter. More...
BA_API void	HttpResRdr_sendFile (IoIntf *io, const char *name, IoStat *st, HttpCommand *cmd)
	Send an IoIntf resource through the current response. More...

Macro Definition Documentation

HttpResRdr_getIo

#define HttpResRdr_getIo

(

o

)

(o)->io

Access the filesystem supplied at construction.

Returns

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

Parameters

o	Required initialized reader.

HttpResRdr_setAuthenticator

#define HttpResRdr_setAuthenticator	(		o,
			authenticator,
			realm
	)		HttpDir_setAuthenticator((HttpDir*)o, authenticator, realm)

Configure inherited authentication and authorization.

Parameters

o	Required initialized reader.
authenticator	Borrowed AuthenticatorIntf pointer, or NULL.
realm	Borrowed AuthorizerIntf pointer, or NULL; despite the historical macro name this argument is not a realm string. See HttpDir::setAuthenticator.

HttpResRdr_setMaxAge

#define HttpResRdr_setMaxAge	(		o,
			maxAgeMA
	)		(o)->maxAge=maxAgeMA

C form of HttpResRdr::setMaxAge.

Parameters

o	Required initialized reader.
maxAgeMA	Lifetime in seconds; zero disables the automatic header.

Typedef Documentation

HttpRdFilter

typedef struct HttpRdFilter HttpRdFilter

Superclass for HttpResRdr filters.

This class is used when designing plugins such as the lspfilter, the LSP plugin.

HttpRdFilter_Service

typedef void(* HttpRdFilter_Service) (struct HttpRdFilter *o, const char *name, IoStat *st, HttpCommand *cmd)

Process a resource selected by a reader's file-extension filter.

Parameters

o	Required installed filter object.
name	Borrowed NUL-terminated path relative to the reader's IoIntf.
st	Borrowed metadata for the resource, valid only during this call.
cmd	Required current request/response container. Handle the response in this callback; no status is returned to request another filter. No argument ownership transfers. The callback must not retain temporary path/metadata pointers or destroy the reader during dispatch.

HttpResRdr

typedef HttpResRdr HttpResRdr

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.

Function Documentation

HttpRdFilter_constructor()

BA_API void HttpRdFilter_constructor	(	HttpRdFilter *	o,
		const char *	ext,
		HttpRdFilter_Service	serviceFp
	)

Initialize a filter without installing it.

Parameters

o	Required filter storage.
ext	Required borrowed extension without a leading dot, for example "lsp". Matching is case-sensitive; retain it while installed.
serviceFp	Required callback, callable while installed.

HttpRdFilter_destructor()

BA_API void HttpRdFilter_destructor

(

HttpRdFilter *

o

)

Unlink a filter from its reader if installed.

Parameters

o	Required initialized filter. Does not free the object or extension. Stop callback users before destroying its storage.

HttpResRdr_constructor()

BA_API void HttpResRdr_constructor	(	HttpResRdr *	o,
		IoIntf *	io,
		const char *	dirName,
		AllocatorIntf *	alloc,
		S8	priority
	)

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.
o	Required storage to initialize.

HttpResRdr_constructor2()

BA_API void HttpResRdr_constructor2	(	HttpResRdr *	o,
		IoIntf *	io,
		const char *	domain,
		const char *	p404,
		AllocatorIntf *	alloc,
		S8	priority
	)

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.
o	Required storage to initialize.

HttpResRdr_destructor()

BA_API void HttpResRdr_destructor

(

HttpResRdr *

o

)

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.

Parameters

o	Required initialized reader.

HttpResRdr_insertPrologDir()

BA_API int HttpResRdr_insertPrologDir	(	HttpResRdr *	o,
		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.

Parameters

o	Required initialized reader.

HttpResRdr_installFilter()

BA_API int HttpResRdr_installFilter	(	HttpResRdr *	o,
		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.

Parameters

o	Required initialized reader.

HttpResRdr_sendFile()

BA_API void HttpResRdr_sendFile	(	IoIntf *	io,
		const char *	name,
		IoStat *	st,
		HttpCommand *	cmd
	)

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.