gecko/netwerk/protocol/http/public/nsIHttpChannel.idl

297 lines
12 KiB
Plaintext
Raw Normal View History

/* -*- 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();
};