Mozilla

• About
• Developers
• Store
• Support
• Products

nsIHttpChannel

---

This interface allows for the modification of HTTP request parameters and the inspection of the resulting HTTP response status and headers when they become available. It is scriptable.

Request Configuration

Modifying request parameters after asyncOpen has been called is an error.

Methods

getRequestHeader

Gets the value of a particular request header.

Syntax:

ACString nsIHttpChannel::getRequestHeader(
	in ACString aHeader) 

Parameters:

aHeader: The case-insensitive name of the request header to query (e.g., "Cache-Control").

Returns:

The value of the request header.

setRequestHeader

Set the value of a particular request header. This method allows, for example, the cookies module to add "Cookie" headers to the outgoing HTTP request.

Syntax:

void nsIHttpChannel::setRequestHeader(
	in ACString aHeader, in ACString aValue,
	in boolean aMerge) 

Parameters:

aHeader: The case-insensitive name of the request header to set (e.g.,

"Cookie").

aValue: The request header value to set (e.g., "X=1").

aMerge: If TRUE, the new header value will be merged with any existing values for the specified header. This flag is ignored if the specified header does not support merging (e.g., the "Content-Type" header can only have one value). The list of headers for which this flag is ignored is an implementation detail. If this flag is FALSE, then the header value will be replaced with the contents of aValue.

Note: If aValue is empty and aMerge is FALSE, the header will be cleared.

nsresult:

NS_OK if successful.

visitRequestHeaders

Visits all request headers.

Note: Calling setRequestHeader while visiting request headers has undefined behavior. Don't do it!

Syntax:

void nsIHttpChannel::visitRequestHeaders(
	in nsIHttpHeaderVisitor aVisitor) 

Parameters:

aVisitor: The header visitor instance.

nsresult:

NS_OK if successful.

Attributes

attribute ACString nsIHttpChannel::requestMethod

Gets and sets the HTTP request method (default is "GET"). Setter is case insensitive; getter returns an uppercase string.

Note: The data for a "POST" or "PUT" request can be configured via nsIUploadChannel, but after setting the upload data, it may still be necessary to set the request method explicitly. The documentation for nsIUploadChannel has further details.

attribute nsIURI nsIHttpChannel::referrer

Gets and sets the HTTP referrer URI. This is the address (URI) of the resource from which this channel's URI was obtained (see RFC2616 section 14.36).

Note: The channel may silently refuse to set the Referrer header if the URI does not pass certain security checks (e.g., an https: URL will never be sent as the referrer for a plaintext HTTP request). The implementation is not required to throw an exception when the referrer URI is rejected.

attribute boolean nsIHttpChannel::allowPipelining

Gets and sets a hint to the channel whether or not the underlying HTTP transaction should be allowed to be pipelined with other transactions. This should be set to FALSE, for example, if the application knows that the corresponding document is likely to be very large. This attribute is TRUE by default, though other factors may prevent pipelining.

attribute unsigned long nsIHttpChannel::redirectionLimit

Gets and sets the number of redirects this channel is allowed to make. If zero, the channel will fail to redirect and will generate a NS_ERROR_REDIRECT_LOOP failure status.

Note: An HTTP redirect results in a new channel being created. If the new channel supports nsIHttpChannel, then the value of its redirectionLimit attribute will be set at one less than the value of the redirected channel's redirectionLimit attribute. The initial value for this attribute may be a configurable preference (depending on the implementation).

Response Information

Accessing response information before the onStartRequest event is an error.

Methods

getResponseHeader

Gets the value of a particular response header.

Syntax:

ACString nsIHttpChannel::getResponseHeader(
	in ACString header)  

Parameters:

header: The case-insensitive name of the response header to query (e.g., "Set-Cookie").

Returns:

The value of the response header.

setResponseHeader

Sets the value of a particular response header. This method allows, for example, the HTML content sink to inform the HTTP channel about HTTP-EQUIV headers found in HTML <META> tags.

Syntax:

void nsIHttpChannel::setResponseHeader(
	in ACString header, in ACString value,
	in boolean merge)  

Parameters:

header: The case-insensitive name of the response header to set (e.g., "Cache-control")

value: The response header value to set (e.g., "no-cache")

merge: If TRUE, the new header value will be merged with any existing values for the specified header. This flag is ignored if the specified header does not support merging (e.g., the "Content-Type" header can only have one value). The list of headers for which this flag is ignored is an implementation detail. If this flag is FALSE, then the header value will be replaced with the contents of value.

Note: If value is empty and merge is FALSE, the header will be cleared.

nsresult:

NS_OK if successful.

visitResponseHeaders

Visits all response headers.

Note: Calling setResponseHeader while visiting response headers has undefined behavior. Don't do it!

Syntax:

void nsIHttpChannel::visitResponseHeaders(
	in nsIHttpHeaderVisitor aVisitor)  

Parameters:

aVisitor: The header visitor instance.

Note: If value is empty and merge is FALSE, the header will be cleared.

nsresult:

NS_OK if successful.

isNoStoreResponse

Checks for "Cache-Control: no-store" response header.

Syntax:

boolean nsIHttpChannel::isNoStoreResponse()  

Parameters:

None.

Returns:

TRUE if the server sent a "Cache-Control: no-store" response header.

FALSE otherwise.

isNoCacheResponse

Checks for Cache-control: no-cache" response header.

Syntax:

boolean nsIHttpChannel::isNoCacheResponse()  

Parameters:

None.

Returns:

TRUE if the server sent the equivalent of a "Cache-control: no-cache" response header. Equivalent response headers include: "Pragma: no-cache", "Expires: 0", and "Expires" with a date value in the past relative to the value of the "Date" header.

FALSE otherwise.

Attributes

readonly attribute unsigned long nsIHttpChannel::responseStatus

Gets the HTTP response code (e.g., 200).

readonly attribute ACString nsIHttpChannel::responseStatusText

Gets the HTTP response status text (e.g., "OK").

Note: This returns the raw (possibly 8-bit) text from the server. No assumptions are made about the charset of the returned text. The implementer is responsible for dealing with these issues.

readonly attribute boolean nsIHttpChannel::requestSucceeded

Returns TRUE if the HTTP response code indicates success. The value of nsIRequest::status will be NS_OK even when processing a 404 response because a 404 response may include a message body that (in some cases) should be shown to the user.

Use this attribute to distinguish server error pages from normal pages, instead of comparing the response status manually against the set of valid response codes, if that is required by your application.

• Site Map
• Security Updates
• Contact Us
• Donate

Portions of this content are © 1998–2009 by individual mozilla.org contributors; content available under a Creative Commons license | Details.

Last modified May 7, 2003 Document History