diff -r 000000000000 -r 6474c204b198 netwerk/protocol/http/nsIHttpChannel.idl --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/netwerk/protocol/http/nsIHttpChannel.idl Wed Dec 31 06:09:35 2014 +0100 @@ -0,0 +1,278 @@ +/* -*- 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. + */ +[scriptable, uuid(a01362a0-5c45-11e2-bcfd-0800200c9a66)] +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"). 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. + * + * @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; + + /** + * Read the proxy URI, which, if non-null, will be used to resolve + * proxies for this channel. + */ + readonly attribute nsIURI proxyURI; + + /** + * 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); + + /** + * 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); + + /** + * 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 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; + + /** + * 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(); + + /** + * 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); +};