| /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ |
| /* ***** BEGIN LICENSE BLOCK ***** |
| * Version: MPL 1.1/GPL 2.0/LGPL 2.1 |
| * |
| * The contents of this file are subject to the Mozilla Public License Version |
| * 1.1 (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * http://www.mozilla.org/MPL/ |
| * |
| * Software distributed under the License is distributed on an "AS IS" basis, |
| * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License |
| * for the specific language governing rights and limitations under the |
| * License. |
| * |
| * The Original Code is Mozilla. |
| * |
| * The Initial Developer of the Original Code is |
| * Netscape Communications. |
| * Portions created by the Initial Developer are Copyright (C) 2001 |
| * the Initial Developer. All Rights Reserved. |
| * |
| * Contributor(s): |
| * Gagan Saksena <gagan@netscape.com> (original author) |
| * Darin Fisher <darin@netscape.com> |
| * |
| * Alternatively, the contents of this file may be used under the terms of |
| * either the GNU General Public License Version 2 or later (the "GPL"), or |
| * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), |
| * in which case the provisions of the GPL or the LGPL are applicable instead |
| * of those above. If you wish to allow use of your version of this file only |
| * under the terms of either the GPL or the LGPL, and not to allow others to |
| * use your version of this file under the terms of the MPL, indicate your |
| * decision by deleting the provisions above and replace them with the notice |
| * and other provisions required by the GPL or the LGPL. If you do not delete |
| * the provisions above, a recipient may use your version of this file under |
| * the terms of any one of the MPL, the GPL or the LGPL. |
| * |
| * ***** END LICENSE BLOCK ***** */ |
| |
| #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. |
| * |
| * @status FROZEN |
| */ |
| [scriptable, uuid(9277fe09-f0cc-4cd9-bbce-581dd94b0260)] |
| 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; |
| |
| /** |
| * 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 <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. |
| */ |
| 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(); |
| }; |
