Public Member Functions | Public Attributes

nsIHttpServer Interface Reference

An interface which represents an HTTP server. More...

import "nsIHttpServer.idl";

Collaboration diagram for nsIHttpServer:

List of all members.

Public Member Functions

void start (in long port)
 Starts up this server, listening upon the given port.
void stop (in nsIHttpServerStoppedCallback callback)
 Shuts down this server if it is running (including the period of time after stop() has been called but before the provided callback has been called).
void registerFile (in string path, in nsILocalFile file)
 Associates the local file represented by the string file with all requests which match request.
void registerPathHandler (in string path, in nsIHttpRequestHandler handler)
 Registers a custom path handler.
void registerErrorHandler (in unsigned long code, in nsIHttpRequestHandler handler)
 Registers a custom error page handler.
void registerDirectory (in string path, in nsILocalFile dir)
 Maps all requests to paths beneath path to the corresponding file beneath dir.
void registerContentType (in string extension, in string type)
 Associates files with the given extension with the given Content-Type when served by this server, in the absence of any file-specific information about the desired Content-Type.
void setIndexHandler (in nsIHttpRequestHandler handler)
 Sets the handler used to display the contents of a directory if the directory contains no index page.
AString getState (in AString path, in AString key)
 Retrieves the string associated with the given key in this, for the given path's saved state.
void setState (in AString path, in AString key, in AString value)
 Sets the string associated with the given key in this, for the given path's saved state.
AString getSharedState (in AString key)
 Retrieves the string associated with the given key in this, in entire-server saved state.
void setSharedState (in AString key, in AString value)
 Sets the string associated with the given key in this, in entire-server saved state.
nsISupports getObjectState (in AString key)
 Retrieves the object associated with the given key in this in object-valued saved state.
void setObjectState (in AString key, in nsISupports value)
 Sets the object associated with the given key in this in object-valued saved state.

Public Attributes

readonly attribute
nsIHttpServerIdentity 
identity
 Represents the locations at which this server is reachable.

Detailed Description

An interface which represents an HTTP server.


Member Function Documentation

nsISupports nsIHttpServer::getObjectState ( in AString  key  ) 

Retrieves the object associated with the given key in this in object-valued saved state.

All keys are initially associated with null.

AString nsIHttpServer::getSharedState ( in AString  key  ) 

Retrieves the string associated with the given key in this, in entire-server saved state.

All keys are initially associated with the empty string.

AString nsIHttpServer::getState ( in AString  path,
in AString  key 
)

Retrieves the string associated with the given key in this, for the given path's saved state.

All keys are initially associated with the empty string.

void nsIHttpServer::registerContentType ( in string  extension,
in string  type 
)

Associates files with the given extension with the given Content-Type when served by this server, in the absence of any file-specific information about the desired Content-Type.

If type is empty, removes any extant mapping, if one is present.

Exceptions:
NS_ERROR_INVALID_ARG if the given type is not a valid header field value, i.e. if it doesn't match the field-value production in RFC 2616
Note:
No syntax checking is done of the given type, beyond ensuring that it is a valid header field value. Behavior when not given a string matching the media-type production in RFC 2616 section 3.7 is undefined. Implementations may choose to define specific behavior for types which do not match the production, such as for CGI functionality.
Implementations MAY treat type as a trusted argument; users who fail to generate this string from trusted data risk security vulnerabilities.
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::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 404 that might not throw.
Note:
If the error handler handles HTTP 500 and throws, behavior is undefined.
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, or null to remove any mapping that might exist; 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::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".
void nsIHttpServer::setObjectState ( in AString  key,
in nsISupports  value 
)

Sets the object associated with the given key in this in object-valued saved state.

The value may be null.

void nsIHttpServer::setSharedState ( in AString  key,
in AString  value 
)

Sets the string associated with the given key in this, in entire-server saved state.

void nsIHttpServer::setState ( in AString  path,
in AString  key,
in AString  value 
)

Sets the string associated with the given key in this, for the given path's saved state.

void nsIHttpServer::start ( in long  port  ) 

Starts up this server, listening upon the given port.

Parameters:
port the port upon which listening should happen, or -1 if no specific port is desired
Exceptions:
NS_ERROR_ALREADY_INITIALIZED if this server is already started
NS_ERROR_NOT_AVAILABLE if the server is not started and cannot be started on the desired port (perhaps because the port is already in use or because the process does not have privileges to do so)
Note:
Behavior is undefined if this method is called after stop() has been called on this but before the provided callback function has been called.
void nsIHttpServer::stop ( in nsIHttpServerStoppedCallback  callback  ) 

Shuts down this server if it is running (including the period of time after stop() has been called but before the provided callback has been called).

Parameters:
callback an asynchronous callback used to notify the user when this server is stopped and all pending requests have been fully served
Exceptions:
NS_ERROR_NULL_POINTER if callback is null
NS_ERROR_UNEXPECTED if this server is not running

Member Data Documentation

Represents the locations at which this server is reachable.


The documentation for this interface was generated from the following file: