nsIHttpChannel.idl
上传用户:goldcmy89
上传日期:2017-12-03
资源大小:2246k
文件大小:12k
源码类别:

PlugIns编程

开发平台:

Visual C++

  1. /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
  2. /* ***** BEGIN LICENSE BLOCK *****
  3.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4.  *
  5.  * The contents of this file are subject to the Mozilla Public License Version
  6.  * 1.1 (the "License"); you may not use this file except in compliance with
  7.  * the License. You may obtain a copy of the License at
  8.  * http://www.mozilla.org/MPL/
  9.  *
  10.  * Software distributed under the License is distributed on an "AS IS" basis,
  11.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12.  * for the specific language governing rights and limitations under the
  13.  * License.
  14.  *
  15.  * The Original Code is Mozilla.
  16.  *
  17.  * The Initial Developer of the Original Code is
  18.  * Netscape Communications.
  19.  * Portions created by the Initial Developer are Copyright (C) 2001
  20.  * the Initial Developer. All Rights Reserved.
  21.  *
  22.  * Contributor(s):
  23.  *   Gagan Saksena <gagan@netscape.com> (original author)
  24.  *   Darin Fisher <darin@netscape.com>
  25.  *
  26.  * Alternatively, the contents of this file may be used under the terms of
  27.  * either the GNU General Public License Version 2 or later (the "GPL"), or
  28.  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29.  * in which case the provisions of the GPL or the LGPL are applicable instead
  30.  * of those above. If you wish to allow use of your version of this file only
  31.  * under the terms of either the GPL or the LGPL, and not to allow others to
  32.  * use your version of this file under the terms of the MPL, indicate your
  33.  * decision by deleting the provisions above and replace them with the notice
  34.  * and other provisions required by the GPL or the LGPL. If you do not delete
  35.  * the provisions above, a recipient may use your version of this file under
  36.  * the terms of any one of the MPL, the GPL or the LGPL.
  37.  *
  38.  * ***** END LICENSE BLOCK ***** */
  39. #include "nsIChannel.idl"
  40. interface nsIHttpHeaderVisitor;
  41. /**
  42.  * nsIHttpChannel
  43.  *
  44.  * This interface allows for the modification of HTTP request parameters and
  45.  * the inspection of the resulting HTTP response status and headers when they
  46.  * become available.
  47.  *
  48.  * @status FROZEN
  49.  */
  50. [scriptable, uuid(9277fe09-f0cc-4cd9-bbce-581dd94b0260)]
  51. interface nsIHttpChannel : nsIChannel
  52. {
  53.     /**************************************************************************
  54.      * REQUEST CONFIGURATION
  55.      *
  56.      * Modifying request parameters after asyncOpen has been called is an error.
  57.      */
  58.     /**
  59.      * Set/get the HTTP request method (default is "GET").  Setter is case
  60.      * insensitive; getter returns an uppercase string.
  61.      *
  62.      * This attribute may only be set before the channel is opened.
  63.      *
  64.      * NOTE: The data for a "POST" or "PUT" request can be configured via
  65.      * nsIUploadChannel; however, after setting the upload data, it may be
  66.      * necessary to set the request method explicitly.  The documentation
  67.      * for nsIUploadChannel has further details.
  68.      *
  69.      * @throws NS_ERROR_IN_PROGRESS if set after the channel has been opened.
  70.      */
  71.     attribute ACString requestMethod;
  72.     /**
  73.      * Get/set the HTTP referrer URI.  This is the address (URI) of the
  74.      * resource from which this channel's URI was obtained (see RFC2616 section
  75.      * 14.36).
  76.      * 
  77.      * This attribute may only be set before the channel is opened.
  78.      *
  79.      * NOTE: The channel may silently refuse to set the Referer header if the
  80.      * URI does not pass certain security checks (e.g., a "https://" URL will
  81.      * never be sent as the referrer for a plaintext HTTP request).  The
  82.      * implementation is not required to throw an exception when the referrer
  83.      * URI is rejected.
  84.      *
  85.      * @throws NS_ERROR_IN_PROGRESS if set after the channel has been opened.
  86.      */
  87.     attribute nsIURI referrer;
  88.     /**
  89.      * Get the value of a particular request header.
  90.      *
  91.      * @param aHeader
  92.      *        The case-insensitive name of the request header to query (e.g.,
  93.      *        "Cache-Control").
  94.      *
  95.      * @return the value of the request header.
  96.      * @throws NS_ERROR_NOT_AVAILABLE if the header is not set.
  97.      */
  98.     ACString getRequestHeader(in ACString aHeader);
  99.     /**
  100.      * Set the value of a particular request header.
  101.      *
  102.      * This method allows, for example, the cookies module to add "Cookie"
  103.      * headers to the outgoing HTTP request.
  104.      *
  105.      * This method may only be called before the channel is opened.
  106.      *
  107.      * @param aHeader
  108.      *        The case-insensitive name of the request header to set (e.g.,
  109.      *        "Cookie").
  110.      * @param aValue
  111.      *        The request header value to set (e.g., "X=1").
  112.      * @param aMerge
  113.      *        If true, the new header value will be merged with any existing
  114.      *        values for the specified header.  This flag is ignored if the
  115.      *        specified header does not support merging (e.g., the "Content-
  116.      *        Type" header can only have one value).  The list of headers for
  117.      *        which this flag is ignored is an implementation detail.  If this
  118.      *        flag is false, then the header value will be replaced with the
  119.      *        contents of |aValue|.
  120.      *
  121.      * If aValue is empty and aMerge is false, the header will be cleared.
  122.      *
  123.      * @throws NS_ERROR_IN_PROGRESS if called after the channel has been
  124.      *         opened.
  125.      */
  126.     void setRequestHeader(in ACString aHeader,
  127.                           in ACString aValue,
  128.                           in boolean aMerge);
  129.     /**
  130.      * Call this method to visit all request headers.  Calling setRequestHeader
  131.      * while visiting request headers has undefined behavior.  Don't do it!
  132.      *
  133.      * @param aVisitor
  134.      *        the header visitor instance.
  135.      */
  136.     void visitRequestHeaders(in nsIHttpHeaderVisitor aVisitor);
  137.     /**
  138.      * This attribute is a hint to the channel to indicate whether or not
  139.      * the underlying HTTP transaction should be allowed to be pipelined
  140.      * with other transactions.  This should be set to FALSE, for example,
  141.      * if the application knows that the corresponding document is likely
  142.      * to be very large.
  143.      *
  144.      * This attribute is true by default, though other factors may prevent
  145.      * pipelining.
  146.      *
  147.      * This attribute may only be set before the channel is opened.
  148.      *
  149.      * @throws NS_ERROR_FAILURE if set after the channel has been opened.
  150.      */
  151.     attribute boolean allowPipelining;
  152.     /**
  153.      * This attribute specifies the number of redirects this channel is allowed
  154.      * to make.  If zero, the channel will fail to redirect and will generate
  155.      * a NS_ERROR_REDIRECT_LOOP failure status.
  156.      *
  157.      * NOTE: An HTTP redirect results in a new channel being created.  If the
  158.      * new channel supports nsIHttpChannel, then it will be assigned a value
  159.      * to its |redirectionLimit| attribute one less than the value of the
  160.      * redirected channel's |redirectionLimit| attribute.  The initial value
  161.      * for this attribute may be a configurable preference (depending on the
  162.      * implementation).
  163.      */
  164.     attribute unsigned long redirectionLimit;
  165.     /**************************************************************************
  166.      * RESPONSE INFO
  167.      *
  168.      * Accessing response info before the onStartRequest event is an error.
  169.      */
  170.     /**
  171.      * Get the HTTP response code (e.g., 200).
  172.      *
  173.      * @throws NS_ERROR_NOT_AVAILABLE if called before the response
  174.      *         has been received (before onStartRequest).
  175.      */
  176.     readonly attribute unsigned long responseStatus;
  177.     /**
  178.      * Get the HTTP response status text (e.g., "OK").
  179.      *
  180.      * NOTE: This returns the raw (possibly 8-bit) text from the server.  There
  181.      * are no assumptions made about the charset of the returned text.  You
  182.      * have been warned!
  183.      *
  184.      * @throws NS_ERROR_NOT_AVAILABLE if called before the response
  185.      *         has been received (before onStartRequest).
  186.      */
  187.     readonly attribute ACString responseStatusText;
  188.     /**
  189.      * Returns true if the HTTP response code indicates success.  The value of
  190.      * nsIRequest::status will be NS_OK even when processing a 404 response
  191.      * because a 404 response may include a message body that (in some cases)
  192.      * should be shown to the user.
  193.      *
  194.      * Use this attribute to distinguish server error pages from normal pages,
  195.      * instead of comparing the response status manually against the set of
  196.      * valid response codes, if that is required by your application.
  197.      *
  198.      * @throws NS_ERROR_NOT_AVAILABLE if called before the response
  199.      *         has been received (before onStartRequest).
  200.      */
  201.     readonly attribute boolean requestSucceeded;
  202.     /**
  203.      * Get the value of a particular response header.
  204.      *
  205.      * @param aHeader
  206.      *        The case-insensitive name of the response header to query (e.g.,
  207.      *        "Set-Cookie").
  208.      *
  209.      * @return the value of the response header.
  210.      *
  211.      * @throws NS_ERROR_NOT_AVAILABLE if called before the response
  212.      *         has been received (before onStartRequest) or if the header is
  213.      *         not set in the response.
  214.      */
  215.     ACString getResponseHeader(in ACString header);
  216.     /**
  217.      * Set the value of a particular response header.
  218.      *
  219.      * This method allows, for example, the HTML content sink to inform the HTTP
  220.      * channel about HTTP-EQUIV headers found in HTML <META> tags.
  221.      *
  222.      * @param aHeader
  223.      *        The case-insensitive name of the response header to set (e.g.,
  224.      *        "Cache-control").
  225.      * @param aValue
  226.      *        The response header value to set (e.g., "no-cache").
  227.      * @param aMerge
  228.      *        If true, the new header value will be merged with any existing
  229.      *        values for the specified header.  This flag is ignored if the
  230.      *        specified header does not support merging (e.g., the "Content-
  231.      *        Type" header can only have one value).  The list of headers for
  232.      *        which this flag is ignored is an implementation detail.  If this
  233.      *        flag is false, then the header value will be replaced with the
  234.      *        contents of |aValue|.
  235.      *
  236.      * If aValue is empty and aMerge is false, the header will be cleared.
  237.      * 
  238.      * @throws NS_ERROR_NOT_AVAILABLE if called before the response
  239.      *         has been received (before onStartRequest).
  240.      * @throws NS_ERROR_ILLEGAL_VALUE if changing the value of this response
  241.      *         header is not allowed.
  242.      */
  243.     void setResponseHeader(in ACString header,
  244.                            in ACString value,
  245.                            in boolean merge);
  246.     /**
  247.      * Call this method to visit all response headers.  Calling
  248.      * setResponseHeader while visiting response headers has undefined
  249.      * behavior.  Don't do it!
  250.      *
  251.      * @param aVisitor
  252.      *        the header visitor instance.
  253.      *
  254.      * @throws NS_ERROR_NOT_AVAILABLE if called before the response
  255.      *         has been received (before onStartRequest).
  256.      */
  257.     void visitResponseHeaders(in nsIHttpHeaderVisitor aVisitor);
  258.     /**
  259.      * Returns true if the server sent a "Cache-Control: no-store" response
  260.      * header.
  261.      *
  262.      * @throws NS_ERROR_NOT_AVAILABLE if called before the response
  263.      *         has been received (before onStartRequest).
  264.      */
  265.     boolean isNoStoreResponse();
  266.     /**
  267.      * Returns true if the server sent the equivalent of a "Cache-control:
  268.      * no-cache" response header.  Equivalent response headers include:
  269.      * "Pragma: no-cache", "Expires: 0", and "Expires" with a date value
  270.      * in the past relative to the value of the "Date" header.
  271.      *
  272.      * @throws NS_ERROR_NOT_AVAILABLE if called before the response
  273.      *         has been received (before onStartRequest).
  274.      */
  275.     boolean isNoCacheResponse();
  276. };