1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/test/httpserver/nsIHttpServer.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,614 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +#include "nsISupports.idl"
1.9 +
1.10 +interface nsIInputStream;
1.11 +interface nsIFile;
1.12 +interface nsIOutputStream;
1.13 +interface nsISimpleEnumerator;
1.14 +
1.15 +interface nsIHttpServer;
1.16 +interface nsIHttpServerStoppedCallback;
1.17 +interface nsIHttpRequestHandler;
1.18 +interface nsIHttpRequest;
1.19 +interface nsIHttpResponse;
1.20 +interface nsIHttpServerIdentity;
1.21 +
1.22 +/**
1.23 + * An interface which represents an HTTP server.
1.24 + */
1.25 +[scriptable, uuid(cea8812e-faa6-4013-9396-f9936cbb74ec)]
1.26 +interface nsIHttpServer : nsISupports
1.27 +{
1.28 + /**
1.29 + * Starts up this server, listening upon the given port.
1.30 + *
1.31 + * @param port
1.32 + * the port upon which listening should happen, or -1 if no specific port is
1.33 + * desired
1.34 + * @throws NS_ERROR_ALREADY_INITIALIZED
1.35 + * if this server is already started
1.36 + * @throws NS_ERROR_NOT_AVAILABLE
1.37 + * if the server is not started and cannot be started on the desired port
1.38 + * (perhaps because the port is already in use or because the process does
1.39 + * not have privileges to do so)
1.40 + * @note
1.41 + * Behavior is undefined if this method is called after stop() has been
1.42 + * called on this but before the provided callback function has been
1.43 + * called.
1.44 + */
1.45 + void start(in long port);
1.46 +
1.47 + /**
1.48 + * Shuts down this server if it is running (including the period of time after
1.49 + * stop() has been called but before the provided callback has been called).
1.50 + *
1.51 + * @param callback
1.52 + * an asynchronous callback used to notify the user when this server is
1.53 + * stopped and all pending requests have been fully served
1.54 + * @throws NS_ERROR_NULL_POINTER
1.55 + * if callback is null
1.56 + * @throws NS_ERROR_UNEXPECTED
1.57 + * if this server is not running
1.58 + */
1.59 + void stop(in nsIHttpServerStoppedCallback callback);
1.60 +
1.61 + /**
1.62 + * Associates the local file represented by the string file with all requests
1.63 + * which match request.
1.64 + *
1.65 + * @param path
1.66 + * the path which is to be mapped to the given file; must begin with "/" and
1.67 + * be a valid URI path (i.e., no query string, hash reference, etc.)
1.68 + * @param file
1.69 + * the file to serve for the given path, or null to remove any mapping that
1.70 + * might exist; this file must exist for the lifetime of the server
1.71 + */
1.72 + void registerFile(in string path, in nsIFile file);
1.73 +
1.74 + /**
1.75 + * Registers a custom path handler.
1.76 + *
1.77 + * @param path
1.78 + * the path on the server (beginning with a "/") which is to be handled by
1.79 + * handler; this path must not include a query string or hash component; it
1.80 + * also should usually be canonicalized, since most browsers will do so
1.81 + * before sending otherwise-matching requests
1.82 + * @param handler
1.83 + * an object which will handle any requests for the given path, or null to
1.84 + * remove any existing handler; if while the server is running the handler
1.85 + * throws an exception while responding to a request, an HTTP 500 response
1.86 + * will be returned
1.87 + * @throws NS_ERROR_INVALID_ARG
1.88 + * if path does not begin with a "/"
1.89 + */
1.90 + void registerPathHandler(in string path, in nsIHttpRequestHandler handler);
1.91 +
1.92 + /**
1.93 + * Registers a custom prefix handler.
1.94 + *
1.95 + * @param prefix
1.96 + * the path on the server (beginning and ending with "/") which is to be
1.97 + * handled by handler; this path must not include a query string or hash
1.98 + * component. All requests that start with this prefix will be directed to
1.99 + * the given handler.
1.100 + * @param handler
1.101 + * an object which will handle any requests for the given path, or null to
1.102 + * remove any existing handler; if while the server is running the handler
1.103 + * throws an exception while responding to a request, an HTTP 500 response
1.104 + * will be returned
1.105 + * @throws NS_ERROR_INVALID_ARG
1.106 + * if path does not begin with a "/" or does not end with a "/"
1.107 + */
1.108 + void registerPrefixHandler(in string prefix, in nsIHttpRequestHandler handler);
1.109 +
1.110 + /**
1.111 + * Registers a custom error page handler.
1.112 + *
1.113 + * @param code
1.114 + * the error code which is to be handled by handler
1.115 + * @param handler
1.116 + * an object which will handle any requests which generate the given status
1.117 + * code, or null to remove any existing handler. If the handler throws an
1.118 + * exception during server operation, fallback is to the genericized error
1.119 + * handler (the x00 version), then to 500, using a user-defined error
1.120 + * handler if one exists or the server default handler otherwise. Fallback
1.121 + * will never occur from a user-provided handler that throws to the same
1.122 + * handler as provided by the server, e.g. a throwing user 404 falls back to
1.123 + * 400, not a server-provided 404 that might not throw.
1.124 + * @note
1.125 + * If the error handler handles HTTP 500 and throws, behavior is undefined.
1.126 + */
1.127 + void registerErrorHandler(in unsigned long code, in nsIHttpRequestHandler handler);
1.128 +
1.129 + /**
1.130 + * Maps all requests to paths beneath path to the corresponding file beneath
1.131 + * dir.
1.132 + *
1.133 + * @param path
1.134 + * the absolute path on the server against which requests will be served
1.135 + * from dir (e.g., "/", "/foo/", etc.); must begin and end with a forward
1.136 + * slash
1.137 + * @param dir
1.138 + * the directory to be used to serve all requests for paths underneath path
1.139 + * (except those further overridden by another, deeper path registered with
1.140 + * another directory); if null, any current mapping for the given path is
1.141 + * removed
1.142 + * @throws NS_ERROR_INVALID_ARG
1.143 + * if dir is non-null and does not exist or is not a directory, or if path
1.144 + * does not begin with and end with a forward slash
1.145 + */
1.146 + void registerDirectory(in string path, in nsIFile dir);
1.147 +
1.148 + /**
1.149 + * Associates files with the given extension with the given Content-Type when
1.150 + * served by this server, in the absence of any file-specific information
1.151 + * about the desired Content-Type. If type is empty, removes any extant
1.152 + * mapping, if one is present.
1.153 + *
1.154 + * @throws NS_ERROR_INVALID_ARG
1.155 + * if the given type is not a valid header field value, i.e. if it doesn't
1.156 + * match the field-value production in RFC 2616
1.157 + * @note
1.158 + * No syntax checking is done of the given type, beyond ensuring that it is
1.159 + * a valid header field value. Behavior when not given a string matching
1.160 + * the media-type production in RFC 2616 section 3.7 is undefined.
1.161 + * Implementations may choose to define specific behavior for types which do
1.162 + * not match the production, such as for CGI functionality.
1.163 + * @note
1.164 + * Implementations MAY treat type as a trusted argument; users who fail to
1.165 + * generate this string from trusted data risk security vulnerabilities.
1.166 + */
1.167 + void registerContentType(in string extension, in string type);
1.168 +
1.169 + /**
1.170 + * Sets the handler used to display the contents of a directory if
1.171 + * the directory contains no index page.
1.172 + *
1.173 + * @param handler
1.174 + * an object which will handle any requests for directories which
1.175 + * do not contain index pages, or null to reset to the default
1.176 + * index handler; if while the server is running the handler
1.177 + * throws an exception while responding to a request, an HTTP 500
1.178 + * response will be returned. An nsIFile corresponding to the
1.179 + * directory is available from the metadata object passed to the
1.180 + * handler, under the key "directory".
1.181 + */
1.182 + void setIndexHandler(in nsIHttpRequestHandler handler);
1.183 +
1.184 + /** Represents the locations at which this server is reachable. */
1.185 + readonly attribute nsIHttpServerIdentity identity;
1.186 +
1.187 + /**
1.188 + * Retrieves the string associated with the given key in this, for the given
1.189 + * path's saved state. All keys are initially associated with the empty
1.190 + * string.
1.191 + */
1.192 + AString getState(in AString path, in AString key);
1.193 +
1.194 + /**
1.195 + * Sets the string associated with the given key in this, for the given path's
1.196 + * saved state.
1.197 + */
1.198 + void setState(in AString path, in AString key, in AString value);
1.199 +
1.200 + /**
1.201 + * Retrieves the string associated with the given key in this, in
1.202 + * entire-server saved state. All keys are initially associated with the
1.203 + * empty string.
1.204 + */
1.205 + AString getSharedState(in AString key);
1.206 +
1.207 + /**
1.208 + * Sets the string associated with the given key in this, in entire-server
1.209 + * saved state.
1.210 + */
1.211 + void setSharedState(in AString key, in AString value);
1.212 +
1.213 + /**
1.214 + * Retrieves the object associated with the given key in this in
1.215 + * object-valued saved state. All keys are initially associated with null.
1.216 + */
1.217 + nsISupports getObjectState(in AString key);
1.218 +
1.219 + /**
1.220 + * Sets the object associated with the given key in this in object-valued
1.221 + * saved state. The value may be null.
1.222 + */
1.223 + void setObjectState(in AString key, in nsISupports value);
1.224 +};
1.225 +
1.226 +/**
1.227 + * An interface through which a notification of the complete stopping (socket
1.228 + * closure, in-flight requests all fully served and responded to) of an HTTP
1.229 + * server may be received.
1.230 + */
1.231 +[scriptable, function, uuid(925a6d33-9937-4c63-abe1-a1c56a986455)]
1.232 +interface nsIHttpServerStoppedCallback : nsISupports
1.233 +{
1.234 + /** Called when the corresponding server has been fully stopped. */
1.235 + void onStopped();
1.236 +};
1.237 +
1.238 +/**
1.239 + * Represents a set of names for a server, one of which is the primary name for
1.240 + * the server and the rest of which are secondary. By default every server will
1.241 + * contain ("http", "localhost", port) and ("http", "127.0.0.1", port) as names,
1.242 + * where port is what was provided to the corresponding server when started;
1.243 + * however, except for their being removed when the corresponding server stops
1.244 + * they have no special importance.
1.245 + */
1.246 +[scriptable, uuid(a89de175-ae8e-4c46-91a5-0dba99bbd284)]
1.247 +interface nsIHttpServerIdentity : nsISupports
1.248 +{
1.249 + /**
1.250 + * The primary scheme at which the corresponding server is located, defaulting
1.251 + * to 'http'. This name will be the value of nsIHttpRequest.scheme for
1.252 + * HTTP/1.0 requests.
1.253 + *
1.254 + * This value is always set when the corresponding server is running. If the
1.255 + * server is not running, this value is set only if it has been set to a
1.256 + * non-default name using setPrimary. In this case reading this value will
1.257 + * throw NS_ERROR_NOT_INITIALIZED.
1.258 + */
1.259 + readonly attribute string primaryScheme;
1.260 +
1.261 + /**
1.262 + * The primary name by which the corresponding server is known, defaulting to
1.263 + * 'localhost'. This name will be the value of nsIHttpRequest.host for
1.264 + * HTTP/1.0 requests.
1.265 + *
1.266 + * This value is always set when the corresponding server is running. If the
1.267 + * server is not running, this value is set only if it has been set to a
1.268 + * non-default name using setPrimary. In this case reading this value will
1.269 + * throw NS_ERROR_NOT_INITIALIZED.
1.270 + */
1.271 + readonly attribute string primaryHost;
1.272 +
1.273 + /**
1.274 + * The primary port on which the corresponding server runs, defaulting to the
1.275 + * associated server's port. This name will be the value of
1.276 + * nsIHttpRequest.port for HTTP/1.0 requests.
1.277 + *
1.278 + * This value is always set when the corresponding server is running. If the
1.279 + * server is not running, this value is set only if it has been set to a
1.280 + * non-default name using setPrimary. In this case reading this value will
1.281 + * throw NS_ERROR_NOT_INITIALIZED.
1.282 + */
1.283 + readonly attribute long primaryPort;
1.284 +
1.285 + /**
1.286 + * Adds a location at which this server may be accessed.
1.287 + *
1.288 + * @throws NS_ERROR_ILLEGAL_VALUE
1.289 + * if scheme or host do not match the scheme or host productions imported
1.290 + * into RFC 2616 from RFC 2396, or if port is not a valid port number
1.291 + */
1.292 + void add(in string scheme, in string host, in long port);
1.293 +
1.294 + /**
1.295 + * Removes this name from the list of names by which the corresponding server
1.296 + * is known. If name is also the primary name for the server, the primary
1.297 + * name reverts to 'http://127.0.0.1' with the associated server's port.
1.298 + *
1.299 + * @throws NS_ERROR_ILLEGAL_VALUE
1.300 + * if scheme or host do not match the scheme or host productions imported
1.301 + * into RFC 2616 from RFC 2396, or if port is not a valid port number
1.302 + * @returns
1.303 + * true if the given name was a name for this server, false otherwise
1.304 + */
1.305 + boolean remove(in string scheme, in string host, in long port);
1.306 +
1.307 + /**
1.308 + * Returns true if the given name is in this, false otherwise.
1.309 + *
1.310 + * @throws NS_ERROR_ILLEGAL_VALUE
1.311 + * if scheme or host do not match the scheme or host productions imported
1.312 + * into RFC 2616 from RFC 2396, or if port is not a valid port number
1.313 + */
1.314 + boolean has(in string scheme, in string host, in long port);
1.315 +
1.316 + /**
1.317 + * Returns the scheme for the name with the given host and port, if one is
1.318 + * present; otherwise returns the empty string.
1.319 + *
1.320 + * @throws NS_ERROR_ILLEGAL_VALUE
1.321 + * if host does not match the host production imported into RFC 2616 from
1.322 + * RFC 2396, or if port is not a valid port number
1.323 + */
1.324 + string getScheme(in string host, in long port);
1.325 +
1.326 + /**
1.327 + * Designates the given name as the primary name in this and adds it to this
1.328 + * if it is not already present.
1.329 + *
1.330 + * @throws NS_ERROR_ILLEGAL_VALUE
1.331 + * if scheme or host do not match the scheme or host productions imported
1.332 + * into RFC 2616 from RFC 2396, or if port is not a valid port number
1.333 + */
1.334 + void setPrimary(in string scheme, in string host, in long port);
1.335 +};
1.336 +
1.337 +/**
1.338 + * A representation of a handler for HTTP requests. The handler is used by
1.339 + * calling its .handle method with data for an incoming request; it is the
1.340 + * handler's job to use that data as it sees fit to make the desired response.
1.341 + *
1.342 + * @note
1.343 + * This interface uses the [function] attribute, so you can pass a
1.344 + * script-defined function with the functionality of handle() to any
1.345 + * method which has a nsIHttpRequestHandler parameter, instead of wrapping
1.346 + * it in an otherwise empty object.
1.347 + */
1.348 +[scriptable, function, uuid(2bbb4db7-d285-42b3-a3ce-142b8cc7e139)]
1.349 +interface nsIHttpRequestHandler : nsISupports
1.350 +{
1.351 + /**
1.352 + * Processes an HTTP request and initializes the passed-in response to reflect
1.353 + * the correct HTTP response.
1.354 + *
1.355 + * If this method throws an exception, externally observable behavior depends
1.356 + * upon whether is being processed asynchronously. If such is the case, the
1.357 + * output is some prefix (perhaps all, perhaps none, perhaps only some) of the
1.358 + * data which would have been sent if, instead, the response had been finished
1.359 + * at that point. If no data has been written, the response has not had
1.360 + * seizePower() called on it, and it is not being asynchronously created, an
1.361 + * error handler will be invoked (usually 500 unless otherwise specified).
1.362 + *
1.363 + * Some uses of nsIHttpRequestHandler may require this method to never throw
1.364 + * an exception; in the general case, however, this method may throw an
1.365 + * exception (causing an HTTP 500 response to occur, if the above conditions
1.366 + * are met).
1.367 + *
1.368 + * @param request
1.369 + * data representing an HTTP request
1.370 + * @param response
1.371 + * an initially-empty response which must be modified to reflect the data
1.372 + * which should be sent as the response to the request described by metadata
1.373 + */
1.374 + void handle(in nsIHttpRequest request, in nsIHttpResponse response);
1.375 +};
1.376 +
1.377 +
1.378 +/**
1.379 + * A representation of the data included in an HTTP request.
1.380 + */
1.381 +[scriptable, uuid(978cf30e-ad73-42ee-8f22-fe0aaf1bf5d2)]
1.382 +interface nsIHttpRequest : nsISupports
1.383 +{
1.384 + /**
1.385 + * The request type for this request (see RFC 2616, section 5.1.1).
1.386 + */
1.387 + readonly attribute string method;
1.388 +
1.389 + /**
1.390 + * The scheme of the requested path, usually 'http' but might possibly be
1.391 + * 'https' if some form of SSL tunneling is in use. Note that this value
1.392 + * cannot be accurately determined unless the incoming request used the
1.393 + * absolute-path form of the request line; it defaults to 'http', so only
1.394 + * if it is something else can you be entirely certain it's correct.
1.395 + */
1.396 + readonly attribute string scheme;
1.397 +
1.398 + /**
1.399 + * The host of the data being requested (e.g. "localhost" for the
1.400 + * http://localhost:8080/file resource). Note that the relevant port on the
1.401 + * host is specified in this.port. This value is in the ASCII character
1.402 + * encoding.
1.403 + */
1.404 + readonly attribute string host;
1.405 +
1.406 + /**
1.407 + * The port on the server on which the request was received.
1.408 + */
1.409 + readonly attribute unsigned long port;
1.410 +
1.411 + /**
1.412 + * The requested path, without any query string (e.g. "/dir/file.txt"). It is
1.413 + * guaranteed to begin with a "/". The individual components in this string
1.414 + * are URL-encoded.
1.415 + */
1.416 + readonly attribute string path;
1.417 +
1.418 + /**
1.419 + * The URL-encoded query string associated with this request, not including
1.420 + * the initial "?", or "" if no query string was present.
1.421 + */
1.422 + readonly attribute string queryString;
1.423 +
1.424 + /**
1.425 + * A string containing the HTTP version of the request (i.e., "1.1"). Leading
1.426 + * zeros for either component of the version will be omitted. (In other
1.427 + * words, if the request contains the version "1.01", this attribute will be
1.428 + * "1.1"; see RFC 2616, section 3.1.)
1.429 + */
1.430 + readonly attribute string httpVersion;
1.431 +
1.432 + /**
1.433 + * Returns the value for the header in this request specified by fieldName.
1.434 + *
1.435 + * @param fieldName
1.436 + * the name of the field whose value is to be gotten; note that since HTTP
1.437 + * header field names are case-insensitive, this method produces equivalent
1.438 + * results for "HeAdER" and "hEADer" as fieldName
1.439 + * @returns
1.440 + * The result is a string containing the individual values of the header,
1.441 + * usually separated with a comma. The headers WWW-Authenticate,
1.442 + * Proxy-Authenticate, and Set-Cookie violate the HTTP specification,
1.443 + * however, and for these headers only the separator string is '\n'.
1.444 + *
1.445 + * @throws NS_ERROR_INVALID_ARG
1.446 + * if fieldName does not constitute a valid header field name
1.447 + * @throws NS_ERROR_NOT_AVAILABLE
1.448 + * if the given header does not exist in this
1.449 + */
1.450 + string getHeader(in string fieldName);
1.451 +
1.452 + /**
1.453 + * Returns true if a header with the given field name exists in this, false
1.454 + * otherwise.
1.455 + *
1.456 + * @param fieldName
1.457 + * the field name whose existence is to be determined in this; note that
1.458 + * since HTTP header field names are case-insensitive, this method produces
1.459 + * equivalent results for "HeAdER" and "hEADer" as fieldName
1.460 + * @throws NS_ERROR_INVALID_ARG
1.461 + * if fieldName does not constitute a valid header field name
1.462 + */
1.463 + boolean hasHeader(in string fieldName);
1.464 +
1.465 + /**
1.466 + * An nsISimpleEnumerator of nsISupportsStrings over the names of the headers
1.467 + * in this request. The header field names in the enumerator may not
1.468 + * necessarily have the same case as they do in the request itself.
1.469 + */
1.470 + readonly attribute nsISimpleEnumerator headers;
1.471 +
1.472 + /**
1.473 + * A stream from which data appearing in the body of this request can be read.
1.474 + */
1.475 + readonly attribute nsIInputStream bodyInputStream;
1.476 +};
1.477 +
1.478 +
1.479 +/**
1.480 + * Represents an HTTP response, as described in RFC 2616, section 6.
1.481 + */
1.482 +[scriptable, uuid(1acd16c2-dc59-42fa-9160-4f26c43c1c21)]
1.483 +interface nsIHttpResponse : nsISupports
1.484 +{
1.485 + /**
1.486 + * Sets the status line for this. If this method is never called on this, the
1.487 + * status line defaults to "HTTP/", followed by the server's default HTTP
1.488 + * version (e.g. "1.1"), followed by " 200 OK".
1.489 + *
1.490 + * @param httpVersion
1.491 + * the HTTP version of this, as a string (e.g. "1.1"); if null, the server
1.492 + * default is used
1.493 + * @param code
1.494 + * the numeric HTTP status code for this
1.495 + * @param description
1.496 + * a human-readable description of code; may be null if no description is
1.497 + * desired
1.498 + * @throws NS_ERROR_INVALID_ARG
1.499 + * if httpVersion is not a valid HTTP version string, statusCode is greater
1.500 + * than 999, or description contains invalid characters
1.501 + * @throws NS_ERROR_NOT_AVAILABLE
1.502 + * if this response is being processed asynchronously and data has been
1.503 + * written to this response's body, or if seizePower() has been called on
1.504 + * this
1.505 + */
1.506 + void setStatusLine(in string httpVersion,
1.507 + in unsigned short statusCode,
1.508 + in string description);
1.509 +
1.510 + /**
1.511 + * Sets the specified header in this.
1.512 + *
1.513 + * @param name
1.514 + * the name of the header; must match the field-name production per RFC 2616
1.515 + * @param value
1.516 + * the value of the header; must match the field-value production per RFC
1.517 + * 2616
1.518 + * @param merge
1.519 + * when true, if the given header already exists in this, the values passed
1.520 + * to this function will be merged into the existing header, per RFC 2616
1.521 + * header semantics (except for the Set-Cookie, WWW-Authenticate, and
1.522 + * Proxy-Authenticate headers, which will treat each such merged header as
1.523 + * an additional instance of the header, for real-world compatibility
1.524 + * reasons); when false, replaces any existing header of the given name (if
1.525 + * any exists) with a new header with the specified value
1.526 + * @throws NS_ERROR_INVALID_ARG
1.527 + * if name or value is not a valid header component
1.528 + * @throws NS_ERROR_NOT_AVAILABLE
1.529 + * if this response is being processed asynchronously and data has been
1.530 + * written to this response's body, or if seizePower() has been called on
1.531 + * this
1.532 + */
1.533 + void setHeader(in string name, in string value, in boolean merge);
1.534 +
1.535 + /**
1.536 + * A stream to which data appearing in the body of this response (or in the
1.537 + * totality of the response if seizePower() is called) should be written.
1.538 + * After this response has been designated as being processed asynchronously,
1.539 + * or after seizePower() has been called on this, subsequent writes will no
1.540 + * longer be buffered and will be written to the underlying transport without
1.541 + * delaying until the entire response is constructed. Write-through may or
1.542 + * may not be synchronous in the implementation, and in any case particular
1.543 + * behavior may not be observable to the HTTP client as intermediate buffers
1.544 + * both in the server socket and in the client may delay written data; be
1.545 + * prepared for delays at any time.
1.546 + *
1.547 + * @throws NS_ERROR_NOT_AVAILABLE
1.548 + * if accessed after this response is fully constructed
1.549 + */
1.550 + readonly attribute nsIOutputStream bodyOutputStream;
1.551 +
1.552 + /**
1.553 + * Writes a string to the response's output stream. This method is merely a
1.554 + * convenient shorthand for writing the same data to bodyOutputStream
1.555 + * directly.
1.556 + *
1.557 + * @note
1.558 + * This method is only guaranteed to work with ASCII data.
1.559 + * @throws NS_ERROR_NOT_AVAILABLE
1.560 + * if called after this response has been fully constructed
1.561 + */
1.562 + void write(in string data);
1.563 +
1.564 + /**
1.565 + * Signals that this response is being constructed asynchronously. Requests
1.566 + * are typically completely constructed during nsIHttpRequestHandler.handle;
1.567 + * however, responses which require significant resources (time, memory,
1.568 + * processing) to construct can be created and sent incrementally by calling
1.569 + * this method during the call to nsIHttpRequestHandler.handle. This method
1.570 + * only has this effect when called during nsIHttpRequestHandler.handle;
1.571 + * behavior is undefined if it is called at a later time. It may be called
1.572 + * multiple times with no ill effect, so long as each call occurs before
1.573 + * finish() is called.
1.574 + *
1.575 + * @throws NS_ERROR_UNEXPECTED
1.576 + * if not initially called within a nsIHttpRequestHandler.handle call or if
1.577 + * called after this response has been finished
1.578 + * @throws NS_ERROR_NOT_AVAILABLE
1.579 + * if seizePower() has been called on this
1.580 + */
1.581 + void processAsync();
1.582 +
1.583 + /**
1.584 + * Seizes complete control of this response (and its connection) from the
1.585 + * server, allowing raw and unfettered access to data being sent in the HTTP
1.586 + * response. Once this method has been called the only property which may be
1.587 + * accessed without an exception being thrown is bodyOutputStream, and the
1.588 + * only methods which may be accessed without an exception being thrown are
1.589 + * write(), finish(), and seizePower() (which may be called multiple times
1.590 + * without ill effect so long as all calls are otherwise allowed).
1.591 + *
1.592 + * After a successful call, all data subsequently written to the body of this
1.593 + * response is written directly to the corresponding connection. (Previously-
1.594 + * written data is silently discarded.) No status line or headers are sent
1.595 + * before doing so; if the response handler wishes to write such data, it must
1.596 + * do so manually. Data generation completes only when finish() is called; it
1.597 + * is not enough to simply call close() on bodyOutputStream.
1.598 + *
1.599 + * @throws NS_ERROR_NOT_AVAILABLE
1.600 + * if processAsync() has been called on this
1.601 + * @throws NS_ERROR_UNEXPECTED
1.602 + * if finish() has been called on this
1.603 + */
1.604 + void seizePower();
1.605 +
1.606 + /**
1.607 + * Signals that construction of this response is complete and that it may be
1.608 + * sent over the network to the client, or if seizePower() has been called
1.609 + * signals that all data has been written and that the underlying connection
1.610 + * may be closed. This method may only be called after processAsync() or
1.611 + * seizePower() has been called. This method is idempotent.
1.612 + *
1.613 + * @throws NS_ERROR_UNEXPECTED
1.614 + * if processAsync() or seizePower() has not already been properly called
1.615 + */
1.616 + void finish();
1.617 +};
