/* -*- 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(b2596105-3d0d-4e6a-824f-0539713bb879)] 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. */ attribute nsIURI referrer; /** * Referrer policies. See ReferrerPolicy.h for more details. */ /* 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; /** * 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. */ 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. */ 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. */ 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 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. */ 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); /** * 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 not yet opened. * * This method provides no explicit conflict resolution. The last * caller to call it wins. * * @throws NS_ERROR_ALREADY_OPENED if called after the channel * has been opened. */ void redirectTo(in nsIURI aNewURI); /** * Identifies the scheduling context for this load. */ [noscript] attribute nsID schedulingContextID; };