Public Member Functions | Public Attributes

nsIHttpChannel Interface Reference

nsIHttpChannel More...

import "nsIHttpChannel.idl";

Inheritance diagram for nsIHttpChannel:
Collaboration diagram for nsIHttpChannel:

List of all members.

Public Member Functions

ACString getRequestHeader (in ACString aHeader)
 Get the value of a particular request header.
void setRequestHeader (in ACString aHeader, in ACString aValue, in boolean aMerge)
 Set the value of a particular request header.
void visitRequestHeaders (in nsIHttpHeaderVisitor aVisitor)
 Call this method to visit all request headers.
ACString getResponseHeader (in ACString header)
 Get the value of a particular response header.
void setResponseHeader (in ACString header, in ACString value, in boolean merge)
 Set the value of a particular response header.
void visitResponseHeaders (in nsIHttpHeaderVisitor aVisitor)
 Call this method to visit all response headers.
boolean isNoStoreResponse ()
 Returns true if the server sent a "Cache-Control: no-store" response header.
boolean isNoCacheResponse ()
 Returns true if the server sent the equivalent of a "Cache-control: no-cache" response header.

Public Attributes

attribute ACString requestMethod
 Set/get the HTTP request method (default is "GET").
attribute nsIURI referrer
 Get/set the HTTP referrer URI.
attribute boolean allowPipelining
 This attribute is a hint to the channel to indicate whether or not the underlying HTTP transaction should be allowed to be pipelined with other transactions.
attribute unsigned long redirectionLimit
 This attribute specifies the number of redirects this channel is allowed to make.
readonly attribute unsigned long responseStatus
 Get the HTTP response code (e.g., 200).
readonly attribute ACString responseStatusText
 Get the HTTP response status text (e.g., "OK").
readonly attribute boolean requestSucceeded
 Returns true if the HTTP response code indicates success.

Detailed Description

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.

Status:
FROZEN

Member Function Documentation

ACString nsIHttpChannel::getRequestHeader ( in ACString  aHeader  ) 

Get the value of a particular request header.

Parameters:
aHeader The case-insensitive name of the request header to query (e.g., "Cache-Control").
Returns:
the value of the request header.
Exceptions:
NS_ERROR_NOT_AVAILABLE if the header is not set.
ACString nsIHttpChannel::getResponseHeader ( in ACString  header  ) 

Get the value of a particular response header.

Parameters:
aHeader The case-insensitive name of the response header to query (e.g., "Set-Cookie").
Returns:
the value of the response header.
Exceptions:
NS_ERROR_NOT_AVAILABLE if called before the response has been received (before onStartRequest) or if the header is not set in the response.
boolean nsIHttpChannel::isNoCacheResponse (  ) 

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.

Exceptions:
NS_ERROR_NOT_AVAILABLE if called before the response has been received (before onStartRequest).
boolean nsIHttpChannel::isNoStoreResponse (  ) 

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

Exceptions:
NS_ERROR_NOT_AVAILABLE if called before the response has been received (before onStartRequest).
void nsIHttpChannel::setRequestHeader ( in ACString  aHeader,
in ACString  aValue,
in boolean  aMerge 
)

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.

This method may only be called before the channel is opened.

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|.

If aValue is empty and aMerge is false, the header will be cleared.

Exceptions:
NS_ERROR_IN_PROGRESS if called after the channel has been opened.
void nsIHttpChannel::setResponseHeader ( in ACString  header,
in ACString  value,
in boolean  merge 
)

Set 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.

Parameters:
aHeader The case-insensitive name of the response header to set (e.g., "Cache-control").
aValue The response header value to set (e.g., "no-cache").
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|.

If aValue is empty and aMerge is false, the header will be cleared.

Exceptions:
NS_ERROR_NOT_AVAILABLE if called before the response has been received (before onStartRequest).
NS_ERROR_ILLEGAL_VALUE if changing the value of this response header is not allowed.
void nsIHttpChannel::visitRequestHeaders ( in nsIHttpHeaderVisitor  aVisitor  ) 

Call this method to visit all request headers.

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

Parameters:
aVisitor the header visitor instance.
void nsIHttpChannel::visitResponseHeaders ( in nsIHttpHeaderVisitor  aVisitor  ) 

Call this method to visit all response headers.

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

Parameters:
aVisitor the header visitor instance.
Exceptions:
NS_ERROR_NOT_AVAILABLE if called before the response has been received (before onStartRequest).

Member Data Documentation

This attribute is a hint to the channel to indicate 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.

This attribute may only be set before the channel is opened.

Exceptions:
NS_ERROR_FAILURE if set after the channel has been opened.
attribute unsigned long nsIHttpChannel::redirectionLimit

This attribute specifies 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 it will be assigned a value to its |redirectionLimit| attribute 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).

Get/set 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).

This attribute may only be set before the channel is opened.

NOTE: The channel may silently refuse to set the Referer header if the URI does not pass certain security checks (e.g., a "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.

Exceptions:
NS_ERROR_IN_PROGRESS if set after the channel has been opened.
attribute ACString nsIHttpChannel::requestMethod

Set/get the HTTP request method (default is "GET").

Setter is case insensitive; getter returns an uppercase string.

This attribute may only be set before the channel is opened.

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

Exceptions:
NS_ERROR_IN_PROGRESS if set after the channel has been opened.

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.

Exceptions:
NS_ERROR_NOT_AVAILABLE if called before the response has been received (before onStartRequest).
readonly attribute unsigned long nsIHttpChannel::responseStatus

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

Exceptions:
NS_ERROR_NOT_AVAILABLE if called before the response has been received (before onStartRequest).
readonly attribute ACString nsIHttpChannel::responseStatusText

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

NOTE: This returns the raw (possibly 8-bit) text from the server. There are no assumptions made about the charset of the returned text. You have been warned!

Exceptions:
NS_ERROR_NOT_AVAILABLE if called before the response has been received (before onStartRequest).

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