nsIHttpResponse Interface Reference


Inheritance diagram for nsIHttpResponse:
Collaboration diagram for nsIHttpResponse:

Public Member Functions

void setStatusLine (in string httpVersion, in unsigned short statusCode, in string description)
void setHeader (in string name, in string value, in boolean merge)
void write (in string data)
void processAsync ()
void seizePower ()
void finish ()

Public Attributes

readonly attribute nsIOutputStream bodyOutputStream

Detailed Description

Represents an HTTP response, as described in RFC 2616, section 6.

Definition at line 513 of file nsIHttpServer.idl.

Member Function Documentation

void nsIHttpResponse::finish ( )

Signals that construction of this response is complete and that it may be sent over the network to the client, or if seizePower() has been called signals that all data has been written and that the underlying connection may be closed. This method may only be called after processAsync() or seizePower() has been called. This method is idempotent.

NS_ERROR_UNEXPECTEDif processAsync() or seizePower() has not already been properly called
void nsIHttpResponse::processAsync ( )

Signals that this response is being constructed asynchronously. Requests are typically completely constructed during nsIHttpRequestHandler.handle; however, responses which require significant resources (time, memory, processing) to construct can be created and sent incrementally by calling this method during the call to nsIHttpRequestHandler.handle. This method only has this effect when called during nsIHttpRequestHandler.handle; behavior is undefined if it is called at a later time. It may be called multiple times with no ill effect, so long as each call occurs before finish() is called.

NS_ERROR_UNEXPECTEDif not initially called within a nsIHttpRequestHandler.handle call or if called after this response has been finished
NS_ERROR_NOT_AVAILABLEif seizePower() has been called on this
void nsIHttpResponse::seizePower ( )

Seizes complete control of this response (and its connection) from the server, allowing raw and unfettered access to data being sent in the HTTP response. Once this method has been called the only property which may be accessed without an exception being thrown is bodyOutputStream, and the only methods which may be accessed without an exception being thrown are write(), finish(), and seizePower() (which may be called multiple times without ill effect so long as all calls are otherwise allowed).

After a successful call, all data subsequently written to the body of this response is written directly to the corresponding connection. (Previously- written data is silently discarded.) No status line or headers are sent before doing so; if the response handler wishes to write such data, it must do so manually. Data generation completes only when finish() is called; it is not enough to simply call close() on bodyOutputStream.

NS_ERROR_NOT_AVAILABLEif processAsync() has been called on this
NS_ERROR_UNEXPECTEDif finish() has been called on this
void nsIHttpResponse::setHeader ( in string  name,
in string  value,
in boolean  merge 

Sets the specified header in this.

namethe name of the header; must match the field-name production per RFC 2616
valuethe value of the header; must match the field-value production per RFC 2616
mergewhen true, if the given header already exists in this, the values passed to this function will be merged into the existing header, per RFC 2616 header semantics (except for the Set-Cookie, WWW-Authenticate, and Proxy-Authenticate headers, which will treat each such merged header as an additional instance of the header, for real-world compatibility reasons); when false, replaces any existing header of the given name (if any exists) with a new header with the specified value
NS_ERROR_INVALID_ARGif name or value is not a valid header component
NS_ERROR_NOT_AVAILABLEif this response is being processed asynchronously and data has been written to this response's body, or if seizePower() has been called on this
void nsIHttpResponse::setStatusLine ( in string  httpVersion,
in unsigned short  statusCode,
in string  description 

Sets the status line for this. If this method is never called on this, the status line defaults to "HTTP/", followed by the server's default HTTP version (e.g. "1.1"), followed by " 200 OK".

httpVersionthe HTTP version of this, as a string (e.g. "1.1"); if null, the server default is used
codethe numeric HTTP status code for this
descriptiona human-readable description of code; may be null if no description is desired
NS_ERROR_INVALID_ARGif httpVersion is not a valid HTTP version string, statusCode is greater than 999, or description contains invalid characters
NS_ERROR_NOT_AVAILABLEif this response is being processed asynchronously and data has been written to this response's body, or if seizePower() has been called on this
void nsIHttpResponse::write ( in string  data)

Writes a string to the response's output stream. This method is merely a convenient shorthand for writing the same data to bodyOutputStream directly.

This method is only guaranteed to work with ASCII data.
NS_ERROR_NOT_AVAILABLEif called after this response has been fully constructed

Member Data Documentation

readonly attribute nsIOutputStream nsIHttpResponse::bodyOutputStream

A stream to which data appearing in the body of this response (or in the totality of the response if seizePower() is called) should be written. After this response has been designated as being processed asynchronously, or after seizePower() has been called on this, subsequent writes will no longer be buffered and will be written to the underlying transport without delaying until the entire response is constructed. Write-through may or may not be synchronous in the implementation, and in any case particular behavior may not be observable to the HTTP client as intermediate buffers both in the server socket and in the client may delay written data; be prepared for delays at any time.

Although in the asynchronous cases writes to the underlying transport are not buffered, care must still be taken not to block for too long on any such writes; it is even possible for deadlock to occur in the case that the server and the client reside in the same process. Write data in small chunks if necessary to avoid this problem.
NS_ERROR_NOT_AVAILABLEif accessed after this response is fully constructed

Definition at line 586 of file nsIHttpServer.idl.

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