mozilla
Your Search Results

    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.
    Inherits from: 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("http://www.example.com/", null, null);
    

    Method overview

    ACString getRequestHeader(in ACString aHeader);
    ACString getResponseHeader(in ACString header);
    boolean isNoCacheResponse();
    boolean isNoStoreResponse();
    void redirectTo(in nsIURI aNewURI);
    void setRequestHeader(in ACString aHeader, in ACString aValue, in boolean aMerge);
    void setResponseHeader(in ACString header, in ACString value, in boolean merge);
    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 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 thrown
    NS_ERROR_FAILURE
    If set after the channel has been opened.
    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 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).
    referrer nsIURI

    Get or set the URI of the HTTP Referer: header. 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 thrown
    NS_ERROR_IN_PROGRESS
    If set after the channel has been opened.
    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 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 thrown
    NS_ERROR_IN_PROGRESS
    If set after the channel has been opened.
    requestSucceeded boolean

    Returns true if the HTTP response code indicates success. The value of nsIRequest.status() will be NS_OK even when processing a 404 File Not Found response because such a 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. Read only.

    Exceptions thrown
    NS_ERROR_NOT_AVAILABLE
    If called before the response has been received (before onStartRequest()).
    responseStatus unsigned long Get the HTTP response code (For example 200). Read only.
    Exceptions thrown
    NS_ERROR_NOT_AVAILABLE
    If called before the response has been received (before onStartRequest()).
    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
    NS_ERROR_NOT_AVAILABLE
    If called before the response has been received (before onStartRequest()).
    referrerPolicy Requires Gecko 36 Read only unsigned long The referrer policy in use for this channel, indicated by one of the constants listed above

    Methods

    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.

    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 is false, then the header value will be replaced with the contents of aValue.
    Exceptions thrown
    NS_ERROR_IN_PROGRESS
    If called after the channel has been opened.

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

    visitRequestHeaders()

    Call this method to visit all request headers. Calling setRequestHeader() while visiting request headers has undefined behavior. Don't do it!

    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. Don't do it!

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

    setReferrerWithPolicy() Requires Gecko 36

    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.