michael@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: #include "nsIChannel.idl" michael@0: michael@0: interface nsIHttpHeaderVisitor; michael@0: michael@0: /** michael@0: * nsIHttpChannel michael@0: * michael@0: * This interface allows for the modification of HTTP request parameters and michael@0: * the inspection of the resulting HTTP response status and headers when they michael@0: * become available. michael@0: */ michael@0: [scriptable, uuid(a01362a0-5c45-11e2-bcfd-0800200c9a66)] michael@0: interface nsIHttpChannel : nsIChannel michael@0: { michael@0: /************************************************************************** michael@0: * REQUEST CONFIGURATION michael@0: * michael@0: * Modifying request parameters after asyncOpen has been called is an error. michael@0: */ michael@0: michael@0: /** michael@0: * Set/get the HTTP request method (default is "GET"). Setter is case michael@0: * insensitive; getter returns an uppercase string. michael@0: * michael@0: * This attribute may only be set before the channel is opened. michael@0: * michael@0: * NOTE: The data for a "POST" or "PUT" request can be configured via michael@0: * nsIUploadChannel; however, after setting the upload data, it may be michael@0: * necessary to set the request method explicitly. The documentation michael@0: * for nsIUploadChannel has further details. michael@0: * michael@0: * @throws NS_ERROR_IN_PROGRESS if set after the channel has been opened. michael@0: */ michael@0: attribute ACString requestMethod; michael@0: michael@0: /** michael@0: * Get/set the HTTP referrer URI. This is the address (URI) of the michael@0: * resource from which this channel's URI was obtained (see RFC2616 section michael@0: * 14.36). michael@0: * michael@0: * This attribute may only be set before the channel is opened. michael@0: * michael@0: * NOTE: The channel may silently refuse to set the Referer header if the michael@0: * URI does not pass certain security checks (e.g., a "https://" URL will michael@0: * never be sent as the referrer for a plaintext HTTP request). The michael@0: * implementation is not required to throw an exception when the referrer michael@0: * URI is rejected. michael@0: * michael@0: * @throws NS_ERROR_IN_PROGRESS if set after the channel has been opened. michael@0: */ michael@0: attribute nsIURI referrer; michael@0: michael@0: /** michael@0: * Read the proxy URI, which, if non-null, will be used to resolve michael@0: * proxies for this channel. michael@0: */ michael@0: readonly attribute nsIURI proxyURI; michael@0: michael@0: /** michael@0: * Get the value of a particular request header. michael@0: * michael@0: * @param aHeader michael@0: * The case-insensitive name of the request header to query (e.g., michael@0: * "Cache-Control"). michael@0: * michael@0: * @return the value of the request header. michael@0: * @throws NS_ERROR_NOT_AVAILABLE if the header is not set. michael@0: */ michael@0: ACString getRequestHeader(in ACString aHeader); michael@0: michael@0: /** michael@0: * Set the value of a particular request header. michael@0: * michael@0: * This method allows, for example, the cookies module to add "Cookie" michael@0: * headers to the outgoing HTTP request. michael@0: * michael@0: * This method may only be called before the channel is opened. michael@0: * michael@0: * @param aHeader michael@0: * The case-insensitive name of the request header to set (e.g., michael@0: * "Cookie"). michael@0: * @param aValue michael@0: * The request header value to set (e.g., "X=1"). michael@0: * @param aMerge michael@0: * If true, the new header value will be merged with any existing michael@0: * values for the specified header. This flag is ignored if the michael@0: * specified header does not support merging (e.g., the "Content- michael@0: * Type" header can only have one value). The list of headers for michael@0: * which this flag is ignored is an implementation detail. If this michael@0: * flag is false, then the header value will be replaced with the michael@0: * contents of |aValue|. michael@0: * michael@0: * If aValue is empty and aMerge is false, the header will be cleared. michael@0: * michael@0: * @throws NS_ERROR_IN_PROGRESS if called after the channel has been michael@0: * opened. michael@0: */ michael@0: void setRequestHeader(in ACString aHeader, michael@0: in ACString aValue, michael@0: in boolean aMerge); michael@0: michael@0: /** michael@0: * Call this method to visit all request headers. Calling setRequestHeader michael@0: * while visiting request headers has undefined behavior. Don't do it! michael@0: * michael@0: * @param aVisitor michael@0: * the header visitor instance. michael@0: */ michael@0: void visitRequestHeaders(in nsIHttpHeaderVisitor aVisitor); michael@0: michael@0: /** michael@0: * This attribute is a hint to the channel to indicate whether or not michael@0: * the underlying HTTP transaction should be allowed to be pipelined michael@0: * with other transactions. This should be set to FALSE, for example, michael@0: * if the application knows that the corresponding document is likely michael@0: * to be very large. michael@0: * michael@0: * This attribute is true by default, though other factors may prevent michael@0: * pipelining. michael@0: * michael@0: * This attribute may only be set before the channel is opened. michael@0: * michael@0: * @throws NS_ERROR_FAILURE if set after the channel has been opened. michael@0: */ michael@0: attribute boolean allowPipelining; michael@0: michael@0: /** michael@0: * This attribute specifies the number of redirects this channel is allowed michael@0: * to make. If zero, the channel will fail to redirect and will generate michael@0: * a NS_ERROR_REDIRECT_LOOP failure status. michael@0: * michael@0: * NOTE: An HTTP redirect results in a new channel being created. If the michael@0: * new channel supports nsIHttpChannel, then it will be assigned a value michael@0: * to its |redirectionLimit| attribute one less than the value of the michael@0: * redirected channel's |redirectionLimit| attribute. The initial value michael@0: * for this attribute may be a configurable preference (depending on the michael@0: * implementation). michael@0: */ michael@0: attribute unsigned long redirectionLimit; michael@0: michael@0: michael@0: /************************************************************************** michael@0: * RESPONSE INFO michael@0: * michael@0: * Accessing response info before the onStartRequest event is an error. michael@0: */ michael@0: michael@0: /** michael@0: * Get the HTTP response code (e.g., 200). michael@0: * michael@0: * @throws NS_ERROR_NOT_AVAILABLE if called before the response michael@0: * has been received (before onStartRequest). michael@0: */ michael@0: readonly attribute unsigned long responseStatus; michael@0: michael@0: /** michael@0: * Get the HTTP response status text (e.g., "OK"). michael@0: * michael@0: * NOTE: This returns the raw (possibly 8-bit) text from the server. There michael@0: * are no assumptions made about the charset of the returned text. You michael@0: * have been warned! michael@0: * michael@0: * @throws NS_ERROR_NOT_AVAILABLE if called before the response michael@0: * has been received (before onStartRequest). michael@0: */ michael@0: readonly attribute ACString responseStatusText; michael@0: michael@0: /** michael@0: * Returns true if the HTTP response code indicates success. The value of michael@0: * nsIRequest::status will be NS_OK even when processing a 404 response michael@0: * because a 404 response may include a message body that (in some cases) michael@0: * should be shown to the user. michael@0: * michael@0: * Use this attribute to distinguish server error pages from normal pages, michael@0: * instead of comparing the response status manually against the set of michael@0: * valid response codes, if that is required by your application. michael@0: * michael@0: * @throws NS_ERROR_NOT_AVAILABLE if called before the response michael@0: * has been received (before onStartRequest). michael@0: */ michael@0: readonly attribute boolean requestSucceeded; michael@0: michael@0: /** michael@0: * Get the value of a particular response header. michael@0: * michael@0: * @param aHeader michael@0: * The case-insensitive name of the response header to query (e.g., michael@0: * "Set-Cookie"). michael@0: * michael@0: * @return the value of the response header. michael@0: * michael@0: * @throws NS_ERROR_NOT_AVAILABLE if called before the response michael@0: * has been received (before onStartRequest) or if the header is michael@0: * not set in the response. michael@0: */ michael@0: ACString getResponseHeader(in ACString header); michael@0: michael@0: /** michael@0: * Set the value of a particular response header. michael@0: * michael@0: * This method allows, for example, the HTML content sink to inform the HTTP michael@0: * channel about HTTP-EQUIV headers found in HTML tags. michael@0: * michael@0: * @param aHeader michael@0: * The case-insensitive name of the response header to set (e.g., michael@0: * "Cache-control"). michael@0: * @param aValue michael@0: * The response header value to set (e.g., "no-cache"). michael@0: * @param aMerge michael@0: * If true, the new header value will be merged with any existing michael@0: * values for the specified header. This flag is ignored if the michael@0: * specified header does not support merging (e.g., the "Content- michael@0: * Type" header can only have one value). The list of headers for michael@0: * which this flag is ignored is an implementation detail. If this michael@0: * flag is false, then the header value will be replaced with the michael@0: * contents of |aValue|. michael@0: * michael@0: * If aValue is empty and aMerge is false, the header will be cleared. michael@0: * michael@0: * @throws NS_ERROR_NOT_AVAILABLE if called before the response michael@0: * has been received (before onStartRequest). michael@0: * @throws NS_ERROR_ILLEGAL_VALUE if changing the value of this response michael@0: * header is not allowed. michael@0: */ michael@0: void setResponseHeader(in ACString header, michael@0: in ACString value, michael@0: in boolean merge); michael@0: michael@0: /** michael@0: * Call this method to visit all response headers. Calling michael@0: * setResponseHeader while visiting response headers has undefined michael@0: * behavior. Don't do it! michael@0: * michael@0: * @param aVisitor michael@0: * the header visitor instance. michael@0: * michael@0: * @throws NS_ERROR_NOT_AVAILABLE if called before the response michael@0: * has been received (before onStartRequest). michael@0: */ michael@0: void visitResponseHeaders(in nsIHttpHeaderVisitor aVisitor); michael@0: michael@0: /** michael@0: * Returns true if the server sent a "Cache-Control: no-store" response michael@0: * header. michael@0: * michael@0: * @throws NS_ERROR_NOT_AVAILABLE if called before the response michael@0: * has been received (before onStartRequest). michael@0: */ michael@0: boolean isNoStoreResponse(); michael@0: michael@0: /** michael@0: * Returns true if the server sent the equivalent of a "Cache-control: michael@0: * no-cache" response header. Equivalent response headers include: michael@0: * "Pragma: no-cache", "Expires: 0", and "Expires" with a date value michael@0: * in the past relative to the value of the "Date" header. michael@0: * michael@0: * @throws NS_ERROR_NOT_AVAILABLE if called before the response michael@0: * has been received (before onStartRequest). michael@0: */ michael@0: boolean isNoCacheResponse(); michael@0: michael@0: /** michael@0: * Instructs the channel to immediately redirect to a new destination. michael@0: * Can only be called on channels not yet opened. michael@0: * michael@0: * This method provides no explicit conflict resolution. The last michael@0: * caller to call it wins. michael@0: * michael@0: * @throws NS_ERROR_ALREADY_OPENED if called after the channel michael@0: * has been opened. michael@0: */ michael@0: void redirectTo(in nsIURI aNewURI); michael@0: };