зеркало из https://github.com/mozilla/pjs.git
98 строки
4.2 KiB
Plaintext
98 строки
4.2 KiB
Plaintext
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, particularly for
|
|
registerDirectory (useful for mapping the contents of directories onto request
|
|
paths), registerPathHandler (for setting a custom handler for a specific path on
|
|
the server, such as CGI functionality), and registerFile (for mapping a file to
|
|
a specific path).
|
|
|
|
Finally, you'll want to start (and later stop) the server. Here's some example
|
|
code which does this:
|
|
|
|
server.start(8080); // port on which server will operate
|
|
|
|
// ...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. Note, however, that doing so will trample over the global
|
|
namespace, and global values defined in MozJSHTTP will leak into your script.
|
|
This may typically be benign, but since some of the global values defined are
|
|
constants (specifically, Cc/Ci/Cr as abbreviations for the classes, interfaces,
|
|
and results properties of Components), it's possible this trampling could
|
|
break your script. In general you should use MozJSHTTP as an XPCOM component
|
|
whenever possible.
|
|
|
|
|
|
Known Issues
|
|
------------
|
|
|
|
While MozJSHTTP runs on Mozilla 1.8 and 1.9 platforms, it doesn't run quite as
|
|
well on 1.8 due to the absence of some APIs, specifically the threading APIs.
|
|
The biggest problem here is that server shutdown (see nsIHttpServer.stop) is not
|
|
guaranteed to complete after all pending requests have been served; if you are
|
|
using the server in 1.8 code, you should probably wait a few seconds after
|
|
calling server.stop() before the host application closes to ensure that all
|
|
requests have completed. Things probably aren't going to break too horribly if
|
|
you don't do this, but better safe than sorry.
|
|
|
|
To be clear: the guarantee that nsIHttpServer.stop says implementations should
|
|
make when possible (that .stop returns only when all pending requests have been
|
|
serviced) cannot be made in a 1.8 environment; it can be made in a 1.9
|
|
environment. Use 1.9 if this matters to you, or hack around it as described
|
|
here.
|
|
|
|
|
|
Other Goodies
|
|
-------------
|
|
|
|
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!
|