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

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.org code.
  16.  *
  17.  * The Initial Developer of the Original Code is
  18.  * Netscape Communications Corporation.
  19.  * Portions created by the Initial Developer are Copyright (C) 1998
  20.  * the Initial Developer. All Rights Reserved.
  21.  *
  22.  * Contributor(s):
  23.  *
  24.  * Alternatively, the contents of this file may be used under the terms of
  25.  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26.  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27.  * in which case the provisions of the GPL or the LGPL are applicable instead
  28.  * of those above. If you wish to allow use of your version of this file only
  29.  * under the terms of either the GPL or the LGPL, and not to allow others to
  30.  * use your version of this file under the terms of the MPL, indicate your
  31.  * decision by deleting the provisions above and replace them with the notice
  32.  * and other provisions required by the GPL or the LGPL. If you do not delete
  33.  * the provisions above, a recipient may use your version of this file under
  34.  * the terms of any one of the MPL, the GPL or the LGPL.
  35.  *
  36.  * ***** END LICENSE BLOCK ***** */
  37. #include "nsIRequest.idl"
  38. interface nsIURI;
  39. interface nsIInterfaceRequestor;
  40. interface nsIInputStream;
  41. interface nsIStreamListener;
  42. /**
  43.  * The nsIChannel interface allows clients to construct "GET" requests for
  44.  * specific protocols, and manage them in a uniform way.  Once a channel is
  45.  * created (via nsIIOService::newChannel), parameters for that request may
  46.  * be set by using the channel attributes, or by QI'ing to a subclass of
  47.  * nsIChannel for protocol-specific parameters.  Then, the URI can be fetched
  48.  * by calling nsIChannel::open or nsIChannel::asyncOpen.
  49.  *
  50.  * After a request has been completed, the channel is still valid for accessing
  51.  * protocol-specific results.  For example, QI'ing to nsIHttpChannel allows
  52.  * response headers to be retrieved for the corresponding http transaction. 
  53.  *
  54.  * @status FROZEN
  55.  */
  56. [scriptable, uuid(c63a055a-a676-4e71-bf3c-6cfa11082018)]
  57. interface nsIChannel : nsIRequest
  58. {
  59.     /**
  60.      * The original URI used to construct the channel. This is used in the case
  61.      * of a redirect or URI "resolution" (e.g. resolving a resource: URI to a
  62.      * file: URI) so that the original pre-redirect URI can still be obtained. 
  63.      *
  64.      * NOTE: this is distinctly different from the http Referer (referring URI),
  65.      * which is typically the page that contained the original URI (accessible
  66.      * from nsIHttpChannel).
  67.      */
  68.     attribute nsIURI originalURI;
  69.     /**
  70.      * The URI corresponding to the channel.  Its value is immutable.
  71.      */
  72.     readonly attribute nsIURI URI;
  73.     /**
  74.      * The owner, corresponding to the entity that is responsible for this
  75.      * channel.  Used by the security manager to grant or deny privileges to
  76.      * mobile code loaded from this channel.
  77.      *
  78.      * NOTE: this is a strong reference to the owner, so if the owner is also
  79.      * holding a strong reference to the channel, care must be taken to 
  80.      * explicitly drop its reference to the channel.
  81.      */
  82.     attribute nsISupports owner;
  83.     /**
  84.      * The notification callbacks for the channel.  This is set by clients, who
  85.      * wish to provide a means to receive progress, status and protocol-specific 
  86.      * notifications.  If this value is NULL, the channel implementation may use
  87.      * the notification callbacks from its load group.  The channel may also
  88.      * query the notification callbacks from its load group if its notification
  89.      * callbacks do not supply the requested interface.
  90.      * 
  91.      * Interfaces commonly requested include: nsIProgressEventSink, nsIPrompt,
  92.      * and nsIAuthPrompt.
  93.      *
  94.      * When the channel is done, it must not continue holding references to
  95.      * this object.
  96.      *
  97.      * NOTE: A channel implementation should take care when "caching" an
  98.      * interface pointer queried from its notification callbacks.  If the
  99.      * notification callbacks are changed, then a cached interface pointer may
  100.      * become invalid and may therefore need to be re-queried.
  101.      */
  102.     attribute nsIInterfaceRequestor notificationCallbacks;
  103.     /**
  104.      * Transport-level security information (if any) corresponding to the channel.
  105.      */
  106.     readonly attribute nsISupports securityInfo;
  107.     /**
  108.      * The MIME type of the channel's content if available. 
  109.      * 
  110.      * NOTE: the content type can often be wrongly specified (e.g., wrong file
  111.      * extension, wrong MIME type, wrong document type stored on a server, etc.),
  112.      * and the caller most likely wants to verify with the actual data.
  113.      *
  114.      * Setting contentType before the channel has been opened provides a hint
  115.      * to the channel as to what the MIME type is.  The channel may ignore this
  116.      * hint in deciding on the actual MIME type that it will report.
  117.      *
  118.      * Setting contentType after onStartRequest has been fired or after open()
  119.      * is called will override the type determined by the channel.
  120.      *
  121.      * Setting contentType between the time that asyncOpen() is called and the
  122.      * time when onStartRequest is fired has undefined behavior at this time.
  123.      *
  124.      * The value of the contentType attribute is a lowercase string.  A value
  125.      * assigned to this attribute will be parsed and normalized as follows:
  126.      *  1- any parameters (delimited with a ';') will be stripped.
  127.      *  2- if a charset parameter is given, then its value will replace the
  128.      *     the contentCharset attribute of the channel.
  129.      *  3- the stripped contentType will be lowercased.
  130.      * Any implementation of nsIChannel must follow these rules.
  131.      */
  132.     attribute ACString contentType;
  133.     /**
  134.      * The character set of the channel's content if available and if applicable.
  135.      * This attribute only applies to textual data.
  136.      *
  137.      * The value of the contentCharset attribute is a mixedcase string.
  138.      */
  139.     attribute ACString contentCharset;
  140.     /**
  141.      * The length of the data associated with the channel if available.  A value
  142.      * of -1 indicates that the content length is unknown.
  143.      *
  144.      * Callers should prefer getting the "content-length" property
  145.      * as 64-bit value by QIing the channel to nsIPropertyBag2,
  146.      * if that interface is exposed by the channel.
  147.      */
  148.     attribute long contentLength;
  149.     /**
  150.      * Synchronously open the channel.
  151.      *
  152.      * @return blocking input stream to the channel's data.
  153.      *
  154.      * NOTE: nsIChannel implementations are not required to implement this
  155.      * method.  Moreover, since this method may block the calling thread, it
  156.      * should not be called on a thread that processes UI events.
  157.      */
  158.     nsIInputStream open();
  159.     /**
  160.      * Asynchronously open this channel.  Data is fed to the specified stream
  161.      * listener as it becomes available.  The stream listener's methods are
  162.      * called on the thread that calls asyncOpen and are not called until
  163.      * after asyncOpen returns.
  164.      *
  165.      * @param aListener the nsIStreamListener implementation
  166.      * @param aContext an opaque parameter forwarded to aListener's methods
  167.      */
  168.     void asyncOpen(in nsIStreamListener aListener, in nsISupports aContext);
  169.     /**************************************************************************
  170.      * Channel specific load flags:
  171.      *
  172.      * Bits 21-31 are reserved for future use by this interface or one of its
  173.      * derivatives (e.g., see nsICachingChannel).
  174.      */
  175.     /**
  176.      * Set (e.g., by the docshell) to indicate whether or not the channel
  177.      * corresponds to a document URI.
  178.      */
  179.     const unsigned long LOAD_DOCUMENT_URI = 1 << 16;
  180.     /** 
  181.      * If the end consumer for this load has been retargeted after discovering 
  182.      * it's content, this flag will be set:
  183.      */
  184.     const unsigned long LOAD_RETARGETED_DOCUMENT_URI = 1 << 17;
  185.     /**
  186.      * This flag is set to indicate that onStopRequest may be followed by
  187.      * another onStartRequest/onStopRequest pair.  This flag is, for example,
  188.      * used by the multipart/replace stream converter.
  189.      */
  190.     const unsigned long LOAD_REPLACE = 1 << 18;
  191.     /**
  192.      * Set (e.g., by the docshell) to indicate whether or not the channel
  193.      * corresponds to an initial document URI load (e.g., link click).
  194.      */
  195.     const unsigned long LOAD_INITIAL_DOCUMENT_URI = 1 << 19;
  196.     /**
  197.      * Set (e.g., by the URILoader) to indicate whether or not the end consumer
  198.      * for this load has been determined.
  199.      */
  200.     const unsigned long LOAD_TARGETED = 1 << 20;
  201. };