Add m-esr52 at 52.6.0

1 files changed, 472 insertions, 0 deletions

diff --git a/netwerk/protocol/http/nsIHttpChannel.idl b/netwerk/protocol/http/nsIHttpChannel.idl
new file mode 100644
index 000000000..75ec2c739
--- /dev/null
+++ b/netwerk/protocol/http/nsIHttpChannel.idl
@@ -0,0 +1,472 @@
+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+#include "nsIChannel.idl"
+
+interface nsIHttpHeaderVisitor;
+
+/**
+ * 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.
+ */
+[builtinclass, scriptable, uuid(c5a4a073-4539-49c7-a3f2-cec3f0619c6c)]
+interface nsIHttpChannel : nsIChannel
+{
+    /**************************************************************************
+     * REQUEST CONFIGURATION
+     *
+     * Modifying request parameters after asyncOpen has been called is an error.
+     */
+
+    /**
+     * Set/get the HTTP request method (default is "GET").  Both setter and
+     * getter are case sensitive.
+     *
+     * 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.
+     *
+     * @throws NS_ERROR_IN_PROGRESS if set after the channel has been opened.
+     */
+    attribute ACString requestMethod;
+
+    /**
+     * 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.
+     *
+     * @throws NS_ERROR_IN_PROGRESS if set after the channel has been opened.
+     * @throws NS_ERROR_FAILURE if used for setting referrer during
+     *         visitRequestHeaders. Getting the value will not throw.
+     */
+    attribute nsIURI referrer;
+
+    /**
+     * Referrer policies. See ReferrerPolicy.h for more details.
+     */
+
+
+    /*   The undefined state, usually used to check the need of
+         overruling document-wide referrer policy. */
+    const unsigned long REFERRER_POLICY_UNSET                      = 4294967295; // UINT32_MAX
+
+    /*   default state, a shorter name for no-referrer-when-downgrade   */
+    const unsigned long REFERRER_POLICY_DEFAULT                    = 0;
+    /*   default state, doesn't send referrer from https->http          */
+    const unsigned long REFERRER_POLICY_NO_REFERRER_WHEN_DOWNGRADE = 0;
+    /*   sends no referrer                                              */
+    const unsigned long REFERRER_POLICY_NO_REFERRER                = 1;
+    /*   only sends the origin of the referring URL                     */
+    const unsigned long REFERRER_POLICY_ORIGIN                     = 2;
+    /*   same as default, but reduced to ORIGIN when cross-origin.      */
+    const unsigned long REFERRER_POLICY_ORIGIN_WHEN_XORIGIN        = 3;
+    /*   always sends the referrer, even on downgrade.                  */
+    const unsigned long REFERRER_POLICY_UNSAFE_URL                 = 4;
+    /*   send referrer when same-origin, no referrer when cross-origin  */
+    const unsigned long REFERRER_POLICY_SAME_ORIGIN                = 5;
+    /*   send origin when request from https->https or http->http(s)
+         No referrer when request from https->http. */
+    const unsigned long REFERRER_POLICY_STRICT_ORIGIN              = 6;
+    /*   send referrer when same-origin,
+         Send origin when cross-origin from https->https or http->http(s)
+         No referrer when request from https->http. */
+    const unsigned long REFERRER_POLICY_STRICT_ORIGIN_WHEN_XORIGIN = 7;
+
+    /**
+     * Get the HTTP referrer policy.  The policy is retrieved from the meta
+     * referrer tag, which can be one of many values (see ReferrerPolicy.h for
+     * more details).
+     */
+    readonly attribute unsigned long referrerPolicy;
+
+    /**
+     * Set the HTTP referrer URI with a referrer policy.
+     * @throws NS_ERROR_FAILURE if called during visitRequestHeaders.
+     */
+    void setReferrerWithPolicy(in nsIURI referrer, in unsigned long referrerPolicy);
+
+    /**
+     * Returns the network protocol used to fetch the resource as identified
+     * by the ALPN Protocol ID.
+     *
+     * @throws NS_ERROR_NOT_AVAILABLE if called before the response
+     *         has been received (before onStartRequest).
+     */
+    readonly attribute ACString protocolVersion;
+
+    /**
+     * size consumed by the response header fields and the response payload body
+     */
+    readonly attribute uint64_t transferSize;
+
+    /**
+     * The size of the message body received by the client,
+     * after removing any applied content-codings
+     */
+    readonly attribute uint64_t decodedBodySize;
+
+    /**
+     * The size in octets of the payload body, prior to removing content-codings
+     */
+    readonly attribute uint64_t encodedBodySize;
+
+    /**
+     * Get the value of a particular request header.
+     *
+     * @param aHeader
+     *        The case-insensitive name of the request header to query (e.g.,
+     *        "Cache-Control").
+     *
+     * @return the value of the request header.
+     * @throws NS_ERROR_NOT_AVAILABLE if the header is not set.
+     */
+    ACString getRequestHeader(in ACString aHeader);
+
+    /**
+     * 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.
+     *
+     * @param aHeader
+     *        The case-insensitive name of the request header to set (e.g.,
+     *        "Cookie").
+     * @param aValue
+     *        The request header value to set (e.g., "X=1").
+     * @param 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.
+     *
+     * @throws NS_ERROR_IN_PROGRESS if called after the channel has been
+     *         opened.
+     * @throws NS_ERROR_FAILURE if called during visitRequestHeaders.
+     */
+    void setRequestHeader(in ACString aHeader,
+                          in ACString aValue,
+                          in boolean aMerge);
+
+    /**
+     * Set a request header with empty value.
+     *
+     * 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.
+     *
+     * @param aHeader
+     *        The case-insensitive name of the request header to set (e.g.,
+     *        "Cookie").
+     *
+     * @throws NS_ERROR_IN_PROGRESS if called after the channel has been
+     *         opened.
+     * @throws NS_ERROR_FAILURE if called during visitRequestHeaders.
+     */
+    void setEmptyRequestHeader(in ACString aHeader);
+
+    /**
+     * Call this method to visit all request headers.  Calling setRequestHeader
+     * while visiting request headers has undefined behavior.  Don't do it!
+     *
+     * @param aVisitor
+     *        the header visitor instance.
+     */
+    void visitRequestHeaders(in nsIHttpHeaderVisitor aVisitor);
+
+    /**
+     * Call this method to visit all non-default (UA-provided) request headers.
+     * Calling setRequestHeader while visiting request headers has undefined
+     * behavior. Don't do it!
+     *
+     * @param aVisitor
+     *        the header visitor instance.
+     */
+    void visitNonDefaultRequestHeaders(in nsIHttpHeaderVisitor aVisitor);
+
+    /**
+     * 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.
+     *
+     * @throws NS_ERROR_FAILURE if set after the channel has been opened.
+     */
+    attribute boolean allowPipelining;
+
+    /**
+     * This attribute of the channel indicates whether or not
+     * the underlying HTTP transaction should be honor stored Strict Transport
+     * Security directives for its principal. It defaults to true. Using
+     * OCSP to bootstrap the HTTPs is the likely use case for setting it to
+     * false.
+     *
+     * This attribute may only be set before the channel is opened.
+     *
+     * @throws NS_ERROR_IN_PROGRESS or NS_ERROR_ALREADY_OPENED
+     *         if called after the channel has been opened.
+     */
+    attribute boolean allowSTS;
+
+    /**
+     * 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).
+     */
+    attribute unsigned long redirectionLimit;
+
+
+    /**************************************************************************
+     * RESPONSE INFO
+     *
+     * Accessing response info before the onStartRequest event is an error.
+     */
+
+    /**
+     * Get the HTTP response code (e.g., 200).
+     *
+     * @throws NS_ERROR_NOT_AVAILABLE if called before the response
+     *         has been received (before onStartRequest).
+     */
+    readonly attribute unsigned long responseStatus;
+
+    /**
+     * 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!
+     *
+     * @throws NS_ERROR_NOT_AVAILABLE if called before the response
+     *         has been received (before onStartRequest).
+     */
+    readonly attribute ACString responseStatusText;
+
+    /**
+     * 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.
+     *
+     * @throws NS_ERROR_NOT_AVAILABLE if called before the response
+     *         has been received (before onStartRequest).
+     */
+    readonly attribute boolean requestSucceeded;
+
+   /** Indicates whether channel should be treated as the main one for the
+    *  current document.  If manually set to true, will always remain true.  Otherwise,
+    *  will be true iff LOAD_DOCUMENT_URI is set in the channel's loadflags.
+    */
+    attribute boolean isMainDocumentChannel;
+
+    /**
+     * Get the value of a particular response header.
+     *
+     * @param aHeader
+     *        The case-insensitive name of the response header to query (e.g.,
+     *        "Set-Cookie").
+     *
+     * @return the value of the response header.
+     *
+     * @throws NS_ERROR_NOT_AVAILABLE if called before the response
+     *         has been received (before onStartRequest) or if the header is
+     *         not set in the response.
+     */
+    ACString getResponseHeader(in ACString header);
+
+    /**
+     * 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.
+     *
+     * @param aHeader
+     *        The case-insensitive name of the response header to set (e.g.,
+     *        "Cache-control").
+     * @param aValue
+     *        The response header value to set (e.g., "no-cache").
+     * @param 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.
+     *
+     * @throws NS_ERROR_NOT_AVAILABLE if called before the response
+     *         has been received (before onStartRequest).
+     * @throws NS_ERROR_ILLEGAL_VALUE if changing the value of this response
+     *         header is not allowed.
+     * @throws NS_ERROR_FAILURE if called during visitResponseHeaders,
+     *         VisitOriginalResponseHeaders or getOriginalResponseHeader.
+     */
+    void setResponseHeader(in ACString header,
+                           in ACString value,
+                           in boolean merge);
+
+    /**
+     * Call this method to visit all response headers.  Calling
+     * setResponseHeader while visiting response headers has undefined
+     * behavior.  Don't do it!
+     *
+     * @param aVisitor
+     *        the header visitor instance.
+     *
+     * @throws NS_ERROR_NOT_AVAILABLE if called before the response
+     *         has been received (before onStartRequest).
+     */
+    void visitResponseHeaders(in nsIHttpHeaderVisitor aVisitor);
+
+     /**
+     * Get the value(s) of a particular response header in the form and order
+     * it has been received from the remote peer. There can be multiple headers
+     * with the same name.
+     *
+     * @param aHeader
+     *        The case-insensitive name of the response header to query (e.g.,
+     *        "Set-Cookie").
+     *
+     * @param aVisitor
+     *        the header visitor instance.
+     *
+     * @throws NS_ERROR_NOT_AVAILABLE if called before the response
+     *         has been received (before onStartRequest) or if the header is
+     *         not set in the response.
+     */
+    void getOriginalResponseHeader(in ACString aHeader,
+                                   in nsIHttpHeaderVisitor aVisitor);
+
+    /**
+     * Call this method to visit all response headers in the form and order as
+     * they have been received from the remote peer.
+     * Calling setResponseHeader while visiting response headers has undefined
+     * behavior.  Don't do it!
+     *
+     * @param aVisitor
+     *        the header visitor instance.
+     *
+     * @throws NS_ERROR_NOT_AVAILABLE if called before the response
+     *         has been received (before onStartRequest).
+     */
+    void visitOriginalResponseHeaders(in nsIHttpHeaderVisitor aVisitor);
+
+    /**
+     * Returns true if the server sent a "Cache-Control: no-store" response
+     * header.
+     *
+     * @throws NS_ERROR_NOT_AVAILABLE if called before the response
+     *         has been received (before onStartRequest).
+     */
+    boolean isNoStoreResponse();
+
+    /**
+     * 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.
+     *
+     * @throws NS_ERROR_NOT_AVAILABLE if called before the response
+     *         has been received (before onStartRequest).
+     */
+    boolean isNoCacheResponse();
+
+    /**
+     * Returns true if the server sent a "Cache-Control: private" response
+     * header.
+     *
+     * @throws NS_ERROR_NOT_AVAILABLE if called before the response
+     *         has been received (before onStartRequest).
+     */
+    boolean isPrivateResponse();
+
+    /**
+     * Instructs the channel to immediately redirect to a new destination.
+     * Can only be called on channels that have not yet called their
+     * listener's OnStartRequest(). Generally that means the latest time
+     * this can be used is one of:
+     *    "http-on-examine-response"
+     *    "http-on-examine-merged-response"
+     *    "http-on-examine-cached-response"
+     *
+     * When non-null URL is set before AsyncOpen:
+     *  we attempt to redirect to the targetURI before we even start building
+     *  and sending the request to the cache or the origin server.
+     *  If the redirect is vetoed, we fail the channel.
+     *
+     * When set between AsyncOpen and first call to OnStartRequest being called:
+     *  we attempt to redirect before we start delivery of network or cached
+     *  response to the listener.  If vetoed, we continue with delivery of
+     *  the original content to the channel listener.
+     *
+     * When passed aTargetURI is null the channel behaves normally (can be
+     * rewritten).
+     *
+     * This method provides no explicit conflict resolution. The last
+     * caller to call it wins.
+     *
+     * @throws NS_ERROR_NOT_AVAILABLE if called after the channel has already
+     *         started to deliver the content to its listener.
+     */
+    void redirectTo(in nsIURI aTargetURI);
+
+    /**
+     * Identifies the request context for this load.
+     */
+    [noscript] attribute nsID requestContextID;
+
+    /**
+     * Unique ID of the channel, shared between parent and child. Needed if
+     * the channel activity needs to be monitored across process boundaries,
+     * like in devtools net monitor. See bug 1274556.
+     */
+    attribute ACString channelId;
+
+    /**
+     * ID of the top-level document's inner window.  Identifies the content
+     * this channels is being load in.
+     */
+    attribute uint64_t topLevelContentWindowId;
+};