MozJSHTTP README
================

MozJSHTTP is a small cross-platform implementation of an HTTP/1.1 server in
JavaScript for the Mozilla platform.

MozJSHTTP may be used as an XPCOM component, as an inline script in a document
with XPCOM privileges, or from the XPCOM shell (xpcshell).  Currently, its most-
supported method of use is from the XPCOM shell, where you can get all the
dynamicity of JS in adding request handlers and the like, but component-based
equivalent functionality is planned.


Using MozJSHTTP as an XPCOM Component
-------------------------------------

First, create an XPT file for nsIHttpServer.idl, using the xpidl tool included
in the Mozilla SDK for the environment in which you wish to run MozJSHTTP.  See
<http://developer.mozilla.org/en/docs/XPIDL:xpidl> for further details on how to
do this.

Next, register httpd.js and nsIHttpServer.xpt in your Mozilla application.  In
Firefox, these simply need to be added to the /components directory of your XPI.
Other applications may require use of regxpcom or other techniques; consult the
applicable documentation for further details.

Finally, create an instance of the server using the following command:

  var server = Components.classes["@mozilla.org/server/jshttp;1"]
                         .createInstance(Components.interfaces.nsIHttpServer);

At this point you'll want to initialize the server, since by default it doesn't
serve many useful paths.  For more information on this, see the IDL docs for the
nsIHttpServer interface in nsIHttpServer.idl.

Finally, you'll want to start (and later stop) the server.  Here's some example
code which does this:

  server.init(8080);  // port number on which server will operate -- REQUIRED
  server.start();

  // ...server now runs and serves requests...

  server.stop();


Using MozJSHTTP as an Inline Script or from xpcshell
----------------------------------------------------

Using MozJSHTTP as a script or from xpcshell isn't very different from using it
as a component; the only real difference lies in how you create an instance of
the server.  To create an instance, do the following:

  var server = new nsHttpServer();

You now can use |server| exactly as you would when |server| was created as an
XPCOM component.

HOWEVER...

Running MozJSHTTP from inline script or from xpcshell has some additional
advantages and disadvantages over running as a component:

Disadvantages:
- MozJSHTTP will trample over the global namespace, and since some of the values
  it defines are constants which have a reasonable chance of being defined
  already, there could be some bad collisions

Advantages:
- you can pass in a handle function as a request handler to registerPathHandler
  and registerErrorHandler without wrapping it in an object implementing the
  proper interfaces
- more to come when and as it makes sense...

Finally, a special testing function, |server|, is provided for use in xpcshell
for quick testing of the server; see the source code for details on its use.
You don't want to use this in a script, however, because doing so will block
until the server is shut down.  It's also a good example of how to use the basic
functionality of MozJSHTTP, if you need one.

Have fun!