nsIChannel
Last changed in Gecko 1.3 To create an HTTP channel, use nsIIOService
with a HTTP URI, for example:
var ios = Components.classes["@mozilla.org/network/io-service;1"] .getService(Components.interfaces.nsIIOService); var ch = ios.newChannel("https://www.example.com/", null, null);
Method overview
void getOriginalResponseHeader(in ACString aHeader, in nsIHttpHeaderVisitor aVisitor); Requires Gecko 49 |
ACString getRequestHeader(in ACString aHeader); |
ACString getResponseHeader(in ACString header); |
boolean isNoCacheResponse(); |
boolean isNoStoreResponse(); |
void redirectTo(in nsIURI aNewURI); |
void setEmptyRequestHeader(in ACString aHeader); Requires Gecko 43 |
void setReferrerWithPolicy(in nsIURI referrer, in unsigned long referrerPolicy); |
void setRequestHeader(in ACString aHeader, in ACString aValue, in boolean aMerge); |
void setResponseHeader(in ACString header, in ACString value, in boolean merge); |
void visitOriginalResponseHeaders(in nsIHttpHeaderVisitor aVisitor); Requires Gecko 49 |
void visitRequestHeaders(in nsIHttpHeaderVisitor aVisitor); |
void visitResponseHeaders(in nsIHttpHeaderVisitor aVisitor); |
Constants
Constant | Description |
REFERRER_POLICY_NO_REFERRER_WHEN_DOWNGRADE |
Default; indicates not to pass on the referrer when downgrading from https to http |
REFERRER_POLICY_NO_REFERRER |
Indicates no referrer will be sent |
REFERRER_POLICY_ORIGIN |
Only send the origin of the referring URI |
REFERRER_POLICY_ORIGIN_WHEN_XORIGIN |
Same as the default; Only send the origin of the referring URI for cross-origin requests |
REFERRER_POLICY_UNSAFE_URL |
Always send the referrer, even when downgrading from https to http |
Attributes
Attribute | Type | Description |
allowPipelining |
boolean |
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 This attribute is Exceptions thrown
|
redirectionLimit |
unsigned long |
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 Note: An HTTP redirect results in a new channel being created. If the new channel supports |
referrer |
|
Get or set the URI of the HTTP 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 Exceptions thrown
|
requestMethod |
ACString |
Set or 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 Exceptions thrown
|
requestSucceeded |
boolean |
Returns Exceptions thrown
|
responseStatus |
unsigned long |
Get the HTTP response code (For example 200). Read only.
Exceptions thrown
|
responseStatusText |
ACString |
Get the HTTP response status text (For example "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! Read only. Exceptions thrown
|
referrerPolicy Read only |
unsigned long |
The referrer policy in use for this channel, indicated by one of the constants listed above |
Methods
getOriginalResponseHeader()
Requires Gecko 49 (Firefox 49 / Thunderbird 49 / SeaMonkey 2.46)
getOriginalResponseHeader()
Requires Gecko 49 (Firefox 49 / Thunderbird 49 / SeaMonkey 2.46)Get the value of a particular original response header, that is, in the same form as it came from the network. I.e. empty headers will have an empty string as value and multiple headers will not be merged as opposed to getResponseHeader()
.
void getOriginalResponseHeader( in ACString aHeader, in nsIHttpHeaderVisitor aVisitor );
Parameters
aHeader
- The case-insensitive name of the response header to query (For example "Set-Cookie").
aVisitor
- An
nsIHttpHeaderVisitor
instance allowing to visit all equally named response headers.
Exceptions thrown
NS_ERROR_NOT_AVAILABLE
- If called before the response has been received (before
onStartRequest()
) or if no header with that name is set in the response.
getRequestHeader()
Get the value of a particular request header.
ACString getRequestHeader( in ACString aHeader );
Parameters
aHeader
- The case-insensitive name of the request header to query (For example "Cache-Control").
Return value
The value of the request header.
Exceptions thrown
NS_ERROR_NOT_AVAILABLE
- If the header is not set.
getResponseHeader()
Get the value of a particular response header.
ACString getResponseHeader( in ACString header );
Parameters
header
- The case-insensitive name of the response header to query (For example "Set-Cookie").
Return value
The value of the response header.
Exceptions thrown
NS_ERROR_NOT_AVAILABLE
- If called before the response has been received (before
onStartRequest()
) or if the header is not set in the response.
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.
boolean isNoCacheResponse();
Parameters
None.
Return value
Returns true
if the server sent the equivalent of a "Cache-control: no-cache" response header, otherwise false
.
Exceptions thrown
NS_ERROR_NOT_AVAILABLE
- If called before the response has been received (before
onStartRequest()
).
isNoStoreResponse()
boolean isNoStoreResponse();
Parameters
None.
Return value
true
if the server sent a "Cache-Control: no-store" response header.
Exceptions thrown
NS_ERROR_NOT_AVAILABLE
- If called before the response has been received (before
onStartRequest()
).
redirectTo()
Instructs the channel to immediately redirect to a new destination. Can only be called on channels not yet opened.
This method provides no explicit conflict resolution. The last caller to call it wins.
void redirectTo( in nsIURI aNewURI );
Parameters
aNewURI
- The new URI to which we should redirect.
Exceptions thrown
NS_ERROR_ALREADY_OPENED
- If called after the channel has been opened.
setEmptyRequestHeader()
Requires Gecko 43 (Firefox 43 / Thunderbird 43 / SeaMonkey 2.40)
setEmptyRequestHeader()
Requires Gecko 43 (Firefox 43 / Thunderbird 43 / SeaMonkey 2.40)This method is called to set an empty value for a particular request header. This should be used with caution in the cases where the behavior of setRequestHeader()
ignoring empty header values is undesirable. This method may only be called before the channel is opened.
void setEmptyRequestHeader( in ACString aHeader );
Parameters
aHeader
- The case-insensitive name of the request header to set (For example "Cookie").
Exceptions thrown
NS_ERROR_IN_PROGRESS
- If called after the channel has been opened.
NS_ERROR_FAILURE
Requires Gecko 48.0- If called during
visitRequestHeaders()
.
setReferrerWithPolicy()
Call this method to set the channel's referrer using the referrer policy indicated with one of the predefined constants.
void setReferrerWithPolicy( in nsIURI aReferrer, in unsigned long aReferrerPolicy );
Parameters
aReferrer
- The URI to base the referrer on.
aReferrerPolicy
- The referrer policy to use when determining the referrer to use.
Exceptions thrown
NS_ERROR_FAILURE
Requires Gecko 48.0- If called during
visitRequestHeaders()
.
setRequestHeader()
This method is called to 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. If aValue is empty and aMerge is false
, the header will be cleared.
void setRequestHeader( in ACString aHeader, in ACString aValue, in boolean aMerge );
Parameters
aHeader
- The case-insensitive name of the request header to query (For example "Cookie").
aValue
- The request header value to set (For example "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 (For example 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 isfalse
, then the header value will be replaced with the contents ofaValue
.
Exceptions thrown
NS_ERROR_IN_PROGRESS
- If called after the channel has been opened.
NS_ERROR_FAILURE
Requires Gecko 48.0- If called during
visitRequestHeaders()
.
setResponseHeader()
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. If value is empty and merge is false
, the header will be cleared.
void setResponseHeader( in ACString header, in ACString value, in boolean merge );
Parameters
header
- The case-insensitive name of the response header to set(For example "Cache-Cookie").
value
- The response header value to set (For example "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 (For example 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 ofvalue
.
Exceptions thrown
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.
NS_ERROR_FAILURE
Requires Gecko 49.0- If called during
visitResponseHeaders()
,visitOriginalResponseHeaders()
orgetOriginalResponseHeader()
.
visitOriginalResponseHeaders()
Requires Gecko 49 (Firefox 49 / Thunderbird 49 / SeaMonkey 2.46)
visitOriginalResponseHeaders()
Requires Gecko 49 (Firefox 49 / Thunderbird 49 / SeaMonkey 2.46)Call this method to visit all original response headers, that is, in the same form as they came from the network. I.e. empty headers will be have an empty string as value and multiple headers will not be merged as opposed to visitResponseHeaders()
.
Warning: Calling setResponseHeader()
while visiting response headers will return a NS_ERROR_FAILURE
.
void visitOriginalResponseHeaders( in nsIHttpHeaderVisitor aVisitor );
Parameters
aVisitor
- An
nsIHttpHeaderVisitor
instance allowing to visit all original response headers.
visitRequestHeaders()
Call this method to visit all request headers.
Warning: Calling setRequestHeader()
, setReferrerWithPolicy()
or setEmptyRequestHeader()
while visiting request headers has undefined behavior until Gecko 47 (Firefox 47.0 / Thunderbird 47.0 / SeaMonkey 2.44). Starting from Gecko 48 (Firefox 48.0 / Thunderbird 48.0 / SeaMonkey 2.45) they will return a NS_ERROR_FAILURE
.
void visitRequestHeaders( in nsIHttpHeaderVisitor aVisitor );
Parameters
aVisitor
- The header visitor instance.
visitResponseHeaders()
Call this method to visit all response headers.
Warning: Calling setResponseHeader()
while visiting response headers has undefined behavior until Gecko 48 (Firefox 48.0 / Thunderbird 48.0 / SeaMonkey 2.45). Starting from Gecko 49 (Firefox 49.0 / Thunderbird 49.0 / SeaMonkey 2.46) it will return a NS_ERROR_FAILURE
.
void visitResponseHeaders( in nsIHttpHeaderVisitor aVisitor );
Parameters
aVisitor
- The header visitor instance.
Exceptions thrown
NS_ERROR_NOT_AVAILABLE
- If called before the response has been received (before
onStartRequest()
).
Note: Starting from Firefox 49, empty headers will be returned in case the preference network.http.keep_empty_response_headers_as_empty_string
is set to true
. Since Firefox 50 the preference defaults to true
.