Songbird / Development / Songbird Add-Ons API Documentation

nsIHttpServer Interface Reference

An interface that represents an HTTP server. Currently only used by the testharness. (HINT HINT!!!!). More...

import "nsIHttpServer.idl";

List of all members.

Public Member Functions

void start (in long port)
void stop ()
void registerFile (in string path, in nsILocalFile file)
void registerPathHandler (in string path, in nsIHttpRequestHandler handler)
void registerErrorHandler (in unsigned long code, in nsIHttpRequestHandler handler)
void registerDirectory (in string path, in nsILocalFile dir)
void setIndexHandler (in nsIHttpRequestHandler handler)


Detailed Description

An interface that represents an HTTP server. Currently only used by the testharness. (HINT HINT!!!!).

Definition at line 56 of file nsIHttpServer.idl.


Member Function Documentation

void nsIHttpServer::start ( in long  port  ) 

Starts up this server, listening upon the given port. This method may throw if the process does not have sufficient privileges to open a socket for the given port, and it also throws when called upon a server which has already been started.

Parameters:
port the port upon which listening should happen, or -1 if no specific port is desired

void nsIHttpServer::stop (  ) 

Shuts down this server if it is running; if it is not, this method is a no-op.

This method will do its best to return after the socket in this server has been closed and all pending requests have completed being served, but this may or may not actually happen, since in some implementations this may not actually be possible. Implementations which can make this promise should make it explicit in implementation documentation.

void nsIHttpServer::registerFile ( in string  path,
in nsILocalFile  file 
)

Associates the local file represented by the string file with all requests which match request.

Parameters:
path the path which is to be mapped to the given file; must begin with "/" and be a valid URI path (i.e., no query string, hash reference, etc.)
file the file to serve for the given path; this file must exist for the lifetime of the server

void nsIHttpServer::registerPathHandler ( in string  path,
in nsIHttpRequestHandler  handler 
)

Registers a custom path handler.

Parameters:
path the path on the server (beginning with a "/") which is to be handled by handler; this path must not include a query string or hash component; it also should usually be canonicalized, since most browsers will do so before sending otherwise-matching requests
handler an object which will handle any requests for the given path, or null to remove any existing handler; if while the server is running the handler throws an exception while responding to a request, an HTTP 500 response will be returned
Exceptions:
NS_ERROR_INVALID_ARG if path does not begin with a "/"

void nsIHttpServer::registerErrorHandler ( in unsigned long  code,
in nsIHttpRequestHandler  handler 
)

Registers a custom error page handler.

Parameters:
code the error code which is to be handled by handler
handler an object which will handle any requests which generate the given status code, or null to remove any existing handler. If the handler throws an exception during server operation, fallback is to the genericized error handler (the x00 version), then to 500, using a user-defined error handler if one exists or the server default handler otherwise. Fallback will never occur from a user-provided handler that throws to the same handler as provided by the server, e.g. a throwing user 404 falls back to 400, not a server-provided 400 that might not throw.
Note:
If the error handler handles HTTP 500 and throws, behavior is undefined.

void nsIHttpServer::registerDirectory ( in string  path,
in nsILocalFile  dir 
)

Maps all requests to paths beneath path to the corresponding file beneath dir.

Parameters:
path the absolute path on the server against which requests will be served from dir (e.g., "/", "/foo/", etc.); must begin and end with a forward slash
dir the directory to be used to serve all requests for paths underneath path (except those further overridden by another, deeper path registered with another directory); if null, any current mapping for the given path is removed
Exceptions:
NS_ERROR_INVALID_ARG if dir is non-null and does not exist or is not a directory, or if path does not begin with and end with a forward slash

void nsIHttpServer::setIndexHandler ( in nsIHttpRequestHandler  handler  ) 

Sets the handler used to display the contents of a directory if the directory contains no index page.

Parameters:
handler an object which will handle any requests for directories which do not contain index pages, or null to reset to the default index handler; if while the server is running the handler throws an exception while responding to a request, an HTTP 500 response will be returned. An nsIFile corresponding to the directory is available from the metadata object passed to the handler, under the key "directory".


The documentation for this interface was generated from the following file:
Generated on Tue Mar 10 14:28:56 2009 for Songbird by  doxygen 1.5.2