michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: #include "nsISupports.idl" michael@0: michael@0: interface nsIInputStream; michael@0: interface nsIFile; michael@0: interface nsIOutputStream; michael@0: interface nsISimpleEnumerator; michael@0: michael@0: interface nsIHttpServer; michael@0: interface nsIHttpServerStoppedCallback; michael@0: interface nsIHttpRequestHandler; michael@0: interface nsIHttpRequest; michael@0: interface nsIHttpResponse; michael@0: interface nsIHttpServerIdentity; michael@0: michael@0: /** michael@0: * An interface which represents an HTTP server. michael@0: */ michael@0: [scriptable, uuid(cea8812e-faa6-4013-9396-f9936cbb74ec)] michael@0: interface nsIHttpServer : nsISupports michael@0: { michael@0: /** michael@0: * Starts up this server, listening upon the given port. michael@0: * michael@0: * @param port michael@0: * the port upon which listening should happen, or -1 if no specific port is michael@0: * desired michael@0: * @throws NS_ERROR_ALREADY_INITIALIZED michael@0: * if this server is already started michael@0: * @throws NS_ERROR_NOT_AVAILABLE michael@0: * if the server is not started and cannot be started on the desired port michael@0: * (perhaps because the port is already in use or because the process does michael@0: * not have privileges to do so) michael@0: * @note michael@0: * Behavior is undefined if this method is called after stop() has been michael@0: * called on this but before the provided callback function has been michael@0: * called. michael@0: */ michael@0: void start(in long port); michael@0: michael@0: /** michael@0: * Shuts down this server if it is running (including the period of time after michael@0: * stop() has been called but before the provided callback has been called). michael@0: * michael@0: * @param callback michael@0: * an asynchronous callback used to notify the user when this server is michael@0: * stopped and all pending requests have been fully served michael@0: * @throws NS_ERROR_NULL_POINTER michael@0: * if callback is null michael@0: * @throws NS_ERROR_UNEXPECTED michael@0: * if this server is not running michael@0: */ michael@0: void stop(in nsIHttpServerStoppedCallback callback); michael@0: michael@0: /** michael@0: * Associates the local file represented by the string file with all requests michael@0: * which match request. michael@0: * michael@0: * @param path michael@0: * the path which is to be mapped to the given file; must begin with "/" and michael@0: * be a valid URI path (i.e., no query string, hash reference, etc.) michael@0: * @param file michael@0: * the file to serve for the given path, or null to remove any mapping that michael@0: * might exist; this file must exist for the lifetime of the server michael@0: */ michael@0: void registerFile(in string path, in nsIFile file); michael@0: michael@0: /** michael@0: * Registers a custom path handler. michael@0: * michael@0: * @param path michael@0: * the path on the server (beginning with a "/") which is to be handled by michael@0: * handler; this path must not include a query string or hash component; it michael@0: * also should usually be canonicalized, since most browsers will do so michael@0: * before sending otherwise-matching requests michael@0: * @param handler michael@0: * an object which will handle any requests for the given path, or null to michael@0: * remove any existing handler; if while the server is running the handler michael@0: * throws an exception while responding to a request, an HTTP 500 response michael@0: * will be returned michael@0: * @throws NS_ERROR_INVALID_ARG michael@0: * if path does not begin with a "/" michael@0: */ michael@0: void registerPathHandler(in string path, in nsIHttpRequestHandler handler); michael@0: michael@0: /** michael@0: * Registers a custom prefix handler. michael@0: * michael@0: * @param prefix michael@0: * the path on the server (beginning and ending with "/") which is to be michael@0: * handled by handler; this path must not include a query string or hash michael@0: * component. All requests that start with this prefix will be directed to michael@0: * the given handler. michael@0: * @param handler michael@0: * an object which will handle any requests for the given path, or null to michael@0: * remove any existing handler; if while the server is running the handler michael@0: * throws an exception while responding to a request, an HTTP 500 response michael@0: * will be returned michael@0: * @throws NS_ERROR_INVALID_ARG michael@0: * if path does not begin with a "/" or does not end with a "/" michael@0: */ michael@0: void registerPrefixHandler(in string prefix, in nsIHttpRequestHandler handler); michael@0: michael@0: /** michael@0: * Registers a custom error page handler. michael@0: * michael@0: * @param code michael@0: * the error code which is to be handled by handler michael@0: * @param handler michael@0: * an object which will handle any requests which generate the given status michael@0: * code, or null to remove any existing handler. If the handler throws an michael@0: * exception during server operation, fallback is to the genericized error michael@0: * handler (the x00 version), then to 500, using a user-defined error michael@0: * handler if one exists or the server default handler otherwise. Fallback michael@0: * will never occur from a user-provided handler that throws to the same michael@0: * handler as provided by the server, e.g. a throwing user 404 falls back to michael@0: * 400, not a server-provided 404 that might not throw. michael@0: * @note michael@0: * If the error handler handles HTTP 500 and throws, behavior is undefined. michael@0: */ michael@0: void registerErrorHandler(in unsigned long code, in nsIHttpRequestHandler handler); michael@0: michael@0: /** michael@0: * Maps all requests to paths beneath path to the corresponding file beneath michael@0: * dir. michael@0: * michael@0: * @param path michael@0: * the absolute path on the server against which requests will be served michael@0: * from dir (e.g., "/", "/foo/", etc.); must begin and end with a forward michael@0: * slash michael@0: * @param dir michael@0: * the directory to be used to serve all requests for paths underneath path michael@0: * (except those further overridden by another, deeper path registered with michael@0: * another directory); if null, any current mapping for the given path is michael@0: * removed michael@0: * @throws NS_ERROR_INVALID_ARG michael@0: * if dir is non-null and does not exist or is not a directory, or if path michael@0: * does not begin with and end with a forward slash michael@0: */ michael@0: void registerDirectory(in string path, in nsIFile dir); michael@0: michael@0: /** michael@0: * Associates files with the given extension with the given Content-Type when michael@0: * served by this server, in the absence of any file-specific information michael@0: * about the desired Content-Type. If type is empty, removes any extant michael@0: * mapping, if one is present. michael@0: * michael@0: * @throws NS_ERROR_INVALID_ARG michael@0: * if the given type is not a valid header field value, i.e. if it doesn't michael@0: * match the field-value production in RFC 2616 michael@0: * @note michael@0: * No syntax checking is done of the given type, beyond ensuring that it is michael@0: * a valid header field value. Behavior when not given a string matching michael@0: * the media-type production in RFC 2616 section 3.7 is undefined. michael@0: * Implementations may choose to define specific behavior for types which do michael@0: * not match the production, such as for CGI functionality. michael@0: * @note michael@0: * Implementations MAY treat type as a trusted argument; users who fail to michael@0: * generate this string from trusted data risk security vulnerabilities. michael@0: */ michael@0: void registerContentType(in string extension, in string type); michael@0: michael@0: /** michael@0: * Sets the handler used to display the contents of a directory if michael@0: * the directory contains no index page. michael@0: * michael@0: * @param handler michael@0: * an object which will handle any requests for directories which michael@0: * do not contain index pages, or null to reset to the default michael@0: * index handler; if while the server is running the handler michael@0: * throws an exception while responding to a request, an HTTP 500 michael@0: * response will be returned. An nsIFile corresponding to the michael@0: * directory is available from the metadata object passed to the michael@0: * handler, under the key "directory". michael@0: */ michael@0: void setIndexHandler(in nsIHttpRequestHandler handler); michael@0: michael@0: /** Represents the locations at which this server is reachable. */ michael@0: readonly attribute nsIHttpServerIdentity identity; michael@0: michael@0: /** michael@0: * Retrieves the string associated with the given key in this, for the given michael@0: * path's saved state. All keys are initially associated with the empty michael@0: * string. michael@0: */ michael@0: AString getState(in AString path, in AString key); michael@0: michael@0: /** michael@0: * Sets the string associated with the given key in this, for the given path's michael@0: * saved state. michael@0: */ michael@0: void setState(in AString path, in AString key, in AString value); michael@0: michael@0: /** michael@0: * Retrieves the string associated with the given key in this, in michael@0: * entire-server saved state. All keys are initially associated with the michael@0: * empty string. michael@0: */ michael@0: AString getSharedState(in AString key); michael@0: michael@0: /** michael@0: * Sets the string associated with the given key in this, in entire-server michael@0: * saved state. michael@0: */ michael@0: void setSharedState(in AString key, in AString value); michael@0: michael@0: /** michael@0: * Retrieves the object associated with the given key in this in michael@0: * object-valued saved state. All keys are initially associated with null. michael@0: */ michael@0: nsISupports getObjectState(in AString key); michael@0: michael@0: /** michael@0: * Sets the object associated with the given key in this in object-valued michael@0: * saved state. The value may be null. michael@0: */ michael@0: void setObjectState(in AString key, in nsISupports value); michael@0: }; michael@0: michael@0: /** michael@0: * An interface through which a notification of the complete stopping (socket michael@0: * closure, in-flight requests all fully served and responded to) of an HTTP michael@0: * server may be received. michael@0: */ michael@0: [scriptable, function, uuid(925a6d33-9937-4c63-abe1-a1c56a986455)] michael@0: interface nsIHttpServerStoppedCallback : nsISupports michael@0: { michael@0: /** Called when the corresponding server has been fully stopped. */ michael@0: void onStopped(); michael@0: }; michael@0: michael@0: /** michael@0: * Represents a set of names for a server, one of which is the primary name for michael@0: * the server and the rest of which are secondary. By default every server will michael@0: * contain ("http", "localhost", port) and ("http", "127.0.0.1", port) as names, michael@0: * where port is what was provided to the corresponding server when started; michael@0: * however, except for their being removed when the corresponding server stops michael@0: * they have no special importance. michael@0: */ michael@0: [scriptable, uuid(a89de175-ae8e-4c46-91a5-0dba99bbd284)] michael@0: interface nsIHttpServerIdentity : nsISupports michael@0: { michael@0: /** michael@0: * The primary scheme at which the corresponding server is located, defaulting michael@0: * to 'http'. This name will be the value of nsIHttpRequest.scheme for michael@0: * HTTP/1.0 requests. michael@0: * michael@0: * This value is always set when the corresponding server is running. If the michael@0: * server is not running, this value is set only if it has been set to a michael@0: * non-default name using setPrimary. In this case reading this value will michael@0: * throw NS_ERROR_NOT_INITIALIZED. michael@0: */ michael@0: readonly attribute string primaryScheme; michael@0: michael@0: /** michael@0: * The primary name by which the corresponding server is known, defaulting to michael@0: * 'localhost'. This name will be the value of nsIHttpRequest.host for michael@0: * HTTP/1.0 requests. michael@0: * michael@0: * This value is always set when the corresponding server is running. If the michael@0: * server is not running, this value is set only if it has been set to a michael@0: * non-default name using setPrimary. In this case reading this value will michael@0: * throw NS_ERROR_NOT_INITIALIZED. michael@0: */ michael@0: readonly attribute string primaryHost; michael@0: michael@0: /** michael@0: * The primary port on which the corresponding server runs, defaulting to the michael@0: * associated server's port. This name will be the value of michael@0: * nsIHttpRequest.port for HTTP/1.0 requests. michael@0: * michael@0: * This value is always set when the corresponding server is running. If the michael@0: * server is not running, this value is set only if it has been set to a michael@0: * non-default name using setPrimary. In this case reading this value will michael@0: * throw NS_ERROR_NOT_INITIALIZED. michael@0: */ michael@0: readonly attribute long primaryPort; michael@0: michael@0: /** michael@0: * Adds a location at which this server may be accessed. michael@0: * michael@0: * @throws NS_ERROR_ILLEGAL_VALUE michael@0: * if scheme or host do not match the scheme or host productions imported michael@0: * into RFC 2616 from RFC 2396, or if port is not a valid port number michael@0: */ michael@0: void add(in string scheme, in string host, in long port); michael@0: michael@0: /** michael@0: * Removes this name from the list of names by which the corresponding server michael@0: * is known. If name is also the primary name for the server, the primary michael@0: * name reverts to 'http://127.0.0.1' with the associated server's port. michael@0: * michael@0: * @throws NS_ERROR_ILLEGAL_VALUE michael@0: * if scheme or host do not match the scheme or host productions imported michael@0: * into RFC 2616 from RFC 2396, or if port is not a valid port number michael@0: * @returns michael@0: * true if the given name was a name for this server, false otherwise michael@0: */ michael@0: boolean remove(in string scheme, in string host, in long port); michael@0: michael@0: /** michael@0: * Returns true if the given name is in this, false otherwise. michael@0: * michael@0: * @throws NS_ERROR_ILLEGAL_VALUE michael@0: * if scheme or host do not match the scheme or host productions imported michael@0: * into RFC 2616 from RFC 2396, or if port is not a valid port number michael@0: */ michael@0: boolean has(in string scheme, in string host, in long port); michael@0: michael@0: /** michael@0: * Returns the scheme for the name with the given host and port, if one is michael@0: * present; otherwise returns the empty string. michael@0: * michael@0: * @throws NS_ERROR_ILLEGAL_VALUE michael@0: * if host does not match the host production imported into RFC 2616 from michael@0: * RFC 2396, or if port is not a valid port number michael@0: */ michael@0: string getScheme(in string host, in long port); michael@0: michael@0: /** michael@0: * Designates the given name as the primary name in this and adds it to this michael@0: * if it is not already present. michael@0: * michael@0: * @throws NS_ERROR_ILLEGAL_VALUE michael@0: * if scheme or host do not match the scheme or host productions imported michael@0: * into RFC 2616 from RFC 2396, or if port is not a valid port number michael@0: */ michael@0: void setPrimary(in string scheme, in string host, in long port); michael@0: }; michael@0: michael@0: /** michael@0: * A representation of a handler for HTTP requests. The handler is used by michael@0: * calling its .handle method with data for an incoming request; it is the michael@0: * handler's job to use that data as it sees fit to make the desired response. michael@0: * michael@0: * @note michael@0: * This interface uses the [function] attribute, so you can pass a michael@0: * script-defined function with the functionality of handle() to any michael@0: * method which has a nsIHttpRequestHandler parameter, instead of wrapping michael@0: * it in an otherwise empty object. michael@0: */ michael@0: [scriptable, function, uuid(2bbb4db7-d285-42b3-a3ce-142b8cc7e139)] michael@0: interface nsIHttpRequestHandler : nsISupports michael@0: { michael@0: /** michael@0: * Processes an HTTP request and initializes the passed-in response to reflect michael@0: * the correct HTTP response. michael@0: * michael@0: * If this method throws an exception, externally observable behavior depends michael@0: * upon whether is being processed asynchronously. If such is the case, the michael@0: * output is some prefix (perhaps all, perhaps none, perhaps only some) of the michael@0: * data which would have been sent if, instead, the response had been finished michael@0: * at that point. If no data has been written, the response has not had michael@0: * seizePower() called on it, and it is not being asynchronously created, an michael@0: * error handler will be invoked (usually 500 unless otherwise specified). michael@0: * michael@0: * Some uses of nsIHttpRequestHandler may require this method to never throw michael@0: * an exception; in the general case, however, this method may throw an michael@0: * exception (causing an HTTP 500 response to occur, if the above conditions michael@0: * are met). michael@0: * michael@0: * @param request michael@0: * data representing an HTTP request michael@0: * @param response michael@0: * an initially-empty response which must be modified to reflect the data michael@0: * which should be sent as the response to the request described by metadata michael@0: */ michael@0: void handle(in nsIHttpRequest request, in nsIHttpResponse response); michael@0: }; michael@0: michael@0: michael@0: /** michael@0: * A representation of the data included in an HTTP request. michael@0: */ michael@0: [scriptable, uuid(978cf30e-ad73-42ee-8f22-fe0aaf1bf5d2)] michael@0: interface nsIHttpRequest : nsISupports michael@0: { michael@0: /** michael@0: * The request type for this request (see RFC 2616, section 5.1.1). michael@0: */ michael@0: readonly attribute string method; michael@0: michael@0: /** michael@0: * The scheme of the requested path, usually 'http' but might possibly be michael@0: * 'https' if some form of SSL tunneling is in use. Note that this value michael@0: * cannot be accurately determined unless the incoming request used the michael@0: * absolute-path form of the request line; it defaults to 'http', so only michael@0: * if it is something else can you be entirely certain it's correct. michael@0: */ michael@0: readonly attribute string scheme; michael@0: michael@0: /** michael@0: * The host of the data being requested (e.g. "localhost" for the michael@0: * http://localhost:8080/file resource). Note that the relevant port on the michael@0: * host is specified in this.port. This value is in the ASCII character michael@0: * encoding. michael@0: */ michael@0: readonly attribute string host; michael@0: michael@0: /** michael@0: * The port on the server on which the request was received. michael@0: */ michael@0: readonly attribute unsigned long port; michael@0: michael@0: /** michael@0: * The requested path, without any query string (e.g. "/dir/file.txt"). It is michael@0: * guaranteed to begin with a "/". The individual components in this string michael@0: * are URL-encoded. michael@0: */ michael@0: readonly attribute string path; michael@0: michael@0: /** michael@0: * The URL-encoded query string associated with this request, not including michael@0: * the initial "?", or "" if no query string was present. michael@0: */ michael@0: readonly attribute string queryString; michael@0: michael@0: /** michael@0: * A string containing the HTTP version of the request (i.e., "1.1"). Leading michael@0: * zeros for either component of the version will be omitted. (In other michael@0: * words, if the request contains the version "1.01", this attribute will be michael@0: * "1.1"; see RFC 2616, section 3.1.) michael@0: */ michael@0: readonly attribute string httpVersion; michael@0: michael@0: /** michael@0: * Returns the value for the header in this request specified by fieldName. michael@0: * michael@0: * @param fieldName michael@0: * the name of the field whose value is to be gotten; note that since HTTP michael@0: * header field names are case-insensitive, this method produces equivalent michael@0: * results for "HeAdER" and "hEADer" as fieldName michael@0: * @returns michael@0: * The result is a string containing the individual values of the header, michael@0: * usually separated with a comma. The headers WWW-Authenticate, michael@0: * Proxy-Authenticate, and Set-Cookie violate the HTTP specification, michael@0: * however, and for these headers only the separator string is '\n'. michael@0: * michael@0: * @throws NS_ERROR_INVALID_ARG michael@0: * if fieldName does not constitute a valid header field name michael@0: * @throws NS_ERROR_NOT_AVAILABLE michael@0: * if the given header does not exist in this michael@0: */ michael@0: string getHeader(in string fieldName); michael@0: michael@0: /** michael@0: * Returns true if a header with the given field name exists in this, false michael@0: * otherwise. michael@0: * michael@0: * @param fieldName michael@0: * the field name whose existence is to be determined in this; note that michael@0: * since HTTP header field names are case-insensitive, this method produces michael@0: * equivalent results for "HeAdER" and "hEADer" as fieldName michael@0: * @throws NS_ERROR_INVALID_ARG michael@0: * if fieldName does not constitute a valid header field name michael@0: */ michael@0: boolean hasHeader(in string fieldName); michael@0: michael@0: /** michael@0: * An nsISimpleEnumerator of nsISupportsStrings over the names of the headers michael@0: * in this request. The header field names in the enumerator may not michael@0: * necessarily have the same case as they do in the request itself. michael@0: */ michael@0: readonly attribute nsISimpleEnumerator headers; michael@0: michael@0: /** michael@0: * A stream from which data appearing in the body of this request can be read. michael@0: */ michael@0: readonly attribute nsIInputStream bodyInputStream; michael@0: }; michael@0: michael@0: michael@0: /** michael@0: * Represents an HTTP response, as described in RFC 2616, section 6. michael@0: */ michael@0: [scriptable, uuid(1acd16c2-dc59-42fa-9160-4f26c43c1c21)] michael@0: interface nsIHttpResponse : nsISupports michael@0: { michael@0: /** michael@0: * Sets the status line for this. If this method is never called on this, the michael@0: * status line defaults to "HTTP/", followed by the server's default HTTP michael@0: * version (e.g. "1.1"), followed by " 200 OK". michael@0: * michael@0: * @param httpVersion michael@0: * the HTTP version of this, as a string (e.g. "1.1"); if null, the server michael@0: * default is used michael@0: * @param code michael@0: * the numeric HTTP status code for this michael@0: * @param description michael@0: * a human-readable description of code; may be null if no description is michael@0: * desired michael@0: * @throws NS_ERROR_INVALID_ARG michael@0: * if httpVersion is not a valid HTTP version string, statusCode is greater michael@0: * than 999, or description contains invalid characters michael@0: * @throws NS_ERROR_NOT_AVAILABLE michael@0: * if this response is being processed asynchronously and data has been michael@0: * written to this response's body, or if seizePower() has been called on michael@0: * this michael@0: */ michael@0: void setStatusLine(in string httpVersion, michael@0: in unsigned short statusCode, michael@0: in string description); michael@0: michael@0: /** michael@0: * Sets the specified header in this. michael@0: * michael@0: * @param name michael@0: * the name of the header; must match the field-name production per RFC 2616 michael@0: * @param value michael@0: * the value of the header; must match the field-value production per RFC michael@0: * 2616 michael@0: * @param merge michael@0: * when true, if the given header already exists in this, the values passed michael@0: * to this function will be merged into the existing header, per RFC 2616 michael@0: * header semantics (except for the Set-Cookie, WWW-Authenticate, and michael@0: * Proxy-Authenticate headers, which will treat each such merged header as michael@0: * an additional instance of the header, for real-world compatibility michael@0: * reasons); when false, replaces any existing header of the given name (if michael@0: * any exists) with a new header with the specified value michael@0: * @throws NS_ERROR_INVALID_ARG michael@0: * if name or value is not a valid header component michael@0: * @throws NS_ERROR_NOT_AVAILABLE michael@0: * if this response is being processed asynchronously and data has been michael@0: * written to this response's body, or if seizePower() has been called on michael@0: * this michael@0: */ michael@0: void setHeader(in string name, in string value, in boolean merge); michael@0: michael@0: /** michael@0: * A stream to which data appearing in the body of this response (or in the michael@0: * totality of the response if seizePower() is called) should be written. michael@0: * After this response has been designated as being processed asynchronously, michael@0: * or after seizePower() has been called on this, subsequent writes will no michael@0: * longer be buffered and will be written to the underlying transport without michael@0: * delaying until the entire response is constructed. Write-through may or michael@0: * may not be synchronous in the implementation, and in any case particular michael@0: * behavior may not be observable to the HTTP client as intermediate buffers michael@0: * both in the server socket and in the client may delay written data; be michael@0: * prepared for delays at any time. michael@0: * michael@0: * @throws NS_ERROR_NOT_AVAILABLE michael@0: * if accessed after this response is fully constructed michael@0: */ michael@0: readonly attribute nsIOutputStream bodyOutputStream; michael@0: michael@0: /** michael@0: * Writes a string to the response's output stream. This method is merely a michael@0: * convenient shorthand for writing the same data to bodyOutputStream michael@0: * directly. michael@0: * michael@0: * @note michael@0: * This method is only guaranteed to work with ASCII data. michael@0: * @throws NS_ERROR_NOT_AVAILABLE michael@0: * if called after this response has been fully constructed michael@0: */ michael@0: void write(in string data); michael@0: michael@0: /** michael@0: * Signals that this response is being constructed asynchronously. Requests michael@0: * are typically completely constructed during nsIHttpRequestHandler.handle; michael@0: * however, responses which require significant resources (time, memory, michael@0: * processing) to construct can be created and sent incrementally by calling michael@0: * this method during the call to nsIHttpRequestHandler.handle. This method michael@0: * only has this effect when called during nsIHttpRequestHandler.handle; michael@0: * behavior is undefined if it is called at a later time. It may be called michael@0: * multiple times with no ill effect, so long as each call occurs before michael@0: * finish() is called. michael@0: * michael@0: * @throws NS_ERROR_UNEXPECTED michael@0: * if not initially called within a nsIHttpRequestHandler.handle call or if michael@0: * called after this response has been finished michael@0: * @throws NS_ERROR_NOT_AVAILABLE michael@0: * if seizePower() has been called on this michael@0: */ michael@0: void processAsync(); michael@0: michael@0: /** michael@0: * Seizes complete control of this response (and its connection) from the michael@0: * server, allowing raw and unfettered access to data being sent in the HTTP michael@0: * response. Once this method has been called the only property which may be michael@0: * accessed without an exception being thrown is bodyOutputStream, and the michael@0: * only methods which may be accessed without an exception being thrown are michael@0: * write(), finish(), and seizePower() (which may be called multiple times michael@0: * without ill effect so long as all calls are otherwise allowed). michael@0: * michael@0: * After a successful call, all data subsequently written to the body of this michael@0: * response is written directly to the corresponding connection. (Previously- michael@0: * written data is silently discarded.) No status line or headers are sent michael@0: * before doing so; if the response handler wishes to write such data, it must michael@0: * do so manually. Data generation completes only when finish() is called; it michael@0: * is not enough to simply call close() on bodyOutputStream. michael@0: * michael@0: * @throws NS_ERROR_NOT_AVAILABLE michael@0: * if processAsync() has been called on this michael@0: * @throws NS_ERROR_UNEXPECTED michael@0: * if finish() has been called on this michael@0: */ michael@0: void seizePower(); michael@0: michael@0: /** michael@0: * Signals that construction of this response is complete and that it may be michael@0: * sent over the network to the client, or if seizePower() has been called michael@0: * signals that all data has been written and that the underlying connection michael@0: * may be closed. This method may only be called after processAsync() or michael@0: * seizePower() has been called. This method is idempotent. michael@0: * michael@0: * @throws NS_ERROR_UNEXPECTED michael@0: * if processAsync() or seizePower() has not already been properly called michael@0: */ michael@0: void finish(); michael@0: };