diff options
Diffstat (limited to 'netwerk/protocol/http/nsIHttpChannel.idl')
| -rw-r--r-- | netwerk/protocol/http/nsIHttpChannel.idl | 472 |
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; +}; |