netwerk/base/public/nsIChannel.idl

   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
  38 #include "nsIRequest.idl"
  39
  40 interface nsIURI;
  41 interface nsIInterfaceRequestor;
  42 interface nsIInputStream;
  43 interface nsIStreamListener;
  44
  45 /**
  46  * The nsIChannel interface allows clients to construct "GET" requests for
  47  * specific protocols, and manage them in a uniform way.  Once a channel is
  48  * created (via nsIIOService::newChannel), parameters for that request may
  49  * be set by using the channel attributes, or by QI'ing to a subclass of
  50  * nsIChannel for protocol-specific parameters.  Then, the URI can be fetched
  51  * by calling nsIChannel::open or nsIChannel::asyncOpen.
  52  *
  53  * After a request has been completed, the channel is still valid for accessing
  54  * protocol-specific results.  For example, QI'ing to nsIHttpChannel allows
  55  * response headers to be retrieved for the corresponding http transaction.
  56  *
  57  * @status FROZEN
  58  */
  59 [scriptable, uuid(c63a055a-a676-4e71-bf3c-6cfa11082018)]
  60 interface nsIChannel : nsIRequest
  61 {
  62     /**
  63      * The original URI used to construct the channel. This is used in
  64      * the case of a redirect or URI "resolution" (e.g. resolving a
  65      * resource: URI to a file: URI) so that the original pre-redirect
  66      * URI can still be obtained.  This is never null.  Attempts to
  67      * set it to null must throw.
  68      *
  69      * NOTE: this is distinctly different from the http Referer (referring URI),
  70      * which is typically the page that contained the original URI (accessible
  71      * from nsIHttpChannel).
  72      */
  73     attribute nsIURI originalURI;
  74
  75     /**
  76      * The URI corresponding to the channel.  Its value is immutable.
  77      */
  78     readonly attribute nsIURI URI;
  79
  80     /**
  81      * The owner, corresponding to the entity that is responsible for this
  82      * channel.  Used by the security manager to grant or deny privileges to
  83      * mobile code loaded from this channel.
  84      *
  85      * NOTE: this is a strong reference to the owner, so if the owner is also
  86      * holding a strong reference to the channel, care must be taken to
  87      * explicitly drop its reference to the channel.
  88      */
  89     attribute nsISupports owner;
  90
  91     /**
  92      * The notification callbacks for the channel.  This is set by clients, who
  93      * wish to provide a means to receive progress, status and protocol-specific
  94      * notifications.  If this value is NULL, the channel implementation may use
  95      * the notification callbacks from its load group.  The channel may also
  96      * query the notification callbacks from its load group if its notification
  97      * callbacks do not supply the requested interface.
  98      *
  99      * Interfaces commonly requested include: nsIProgressEventSink, nsIPrompt,
 100      * and nsIAuthPrompt/nsIAuthPrompt2.
 101      *
 102      * When the channel is done, it must not continue holding references to
 103      * this object.
 104      *
 105      * NOTE: A channel implementation should take care when "caching" an
 106      * interface pointer queried from its notification callbacks.  If the
 107      * notification callbacks are changed, then a cached interface pointer may
 108      * become invalid and may therefore need to be re-queried.
 109      */
 110     attribute nsIInterfaceRequestor notificationCallbacks;
 111
 112     /**
 113      * Transport-level security information (if any) corresponding to the channel.
 114      */
 115     readonly attribute nsISupports securityInfo;
 116
 117     /**
 118      * The MIME type of the channel's content if available.
 119      *
 120      * NOTE: the content type can often be wrongly specified (e.g., wrong file
 121      * extension, wrong MIME type, wrong document type stored on a server, etc.),
 122      * and the caller most likely wants to verify with the actual data.
 123      *
 124      * Setting contentType before the channel has been opened provides a hint
 125      * to the channel as to what the MIME type is.  The channel may ignore this
 126      * hint in deciding on the actual MIME type that it will report.
 127      *
 128      * Setting contentType after onStartRequest has been fired or after open()
 129      * is called will override the type determined by the channel.
 130      *
 131      * Setting contentType between the time that asyncOpen() is called and the
 132      * time when onStartRequest is fired has undefined behavior at this time.
 133      *
 134      * The value of the contentType attribute is a lowercase string.  A value
 135      * assigned to this attribute will be parsed and normalized as follows:
 136      *  1- any parameters (delimited with a ';') will be stripped.
 137      *  2- if a charset parameter is given, then its value will replace the
 138      *     the contentCharset attribute of the channel.
 139      *  3- the stripped contentType will be lowercased.
 140      * Any implementation of nsIChannel must follow these rules.
 141      */
 142     attribute ACString contentType;
 143
 144     /**
 145      * The character set of the channel's content if available and if applicable.
 146      * This attribute only applies to textual data.
 147      *
 148      * The value of the contentCharset attribute is a mixedcase string.
 149      */
 150     attribute ACString contentCharset;
 151
 152     /**
 153      * The length of the data associated with the channel if available.  A value
 154      * of -1 indicates that the content length is unknown.
 155      *
 156      * Callers should prefer getting the "content-length" property
 157      * as 64-bit value by QIing the channel to nsIPropertyBag2,
 158      * if that interface is exposed by the channel.
 159      */
 160     attribute long contentLength;
 161
 162     /**
 163      * Synchronously open the channel.
 164      *
 165      * @return blocking input stream to the channel's data.
 166      *
 167      * NOTE: nsIChannel implementations are not required to implement this
 168      * method.  Moreover, since this method may block the calling thread, it
 169      * should not be called on a thread that processes UI events.
 170      *
 171      * NOTE: Implementations should throw NS_ERROR_IN_PROGRESS if the channel
 172      * is reopened.
 173      */
 174     nsIInputStream open();
 175
 176     /**
 177      * Asynchronously open this channel.  Data is fed to the specified stream
 178      * listener as it becomes available.  The stream listener's methods are
 179      * called on the thread that calls asyncOpen and are not called until
 180      * after asyncOpen returns.  If asyncOpen returns successfully, the
 181      * channel promises to call at least onStartRequest and onStopRequest.
 182      *
 183      * If the nsIRequest object passed to the stream listener's methods is not
 184      * this channel, an appropriate onChannelRedirect notification needs to be
 185      * sent to the notification callbacks before onStartRequest is called.
 186      * Once onStartRequest is called, all following method calls on aListener
 187      * will get the request that was passed to onStartRequest.
 188      *
 189      * If the channel's and loadgroup's notification callbacks do not provide
 190      * an nsIChannelEventSink when onChannelRedirect would be called, that's
 191      * equivalent to having called onChannelRedirect.
 192      *
 193      * If asyncOpen returns successfully, the channel is responsible for
 194      * keeping itself alive until it has called onStopRequest on aListener or
 195      * called onChannelRedirect.
 196      *
 197      * Implementations are allowed to synchronously add themselves to the
 198      * associated load group (if any).
 199      *
 200      * NOTE: Implementations should throw NS_ERROR_ALREADY_OPENED if the
 201      * channel is reopened.
 202      *
 203      * @param aListener the nsIStreamListener implementation
 204      * @param aContext an opaque parameter forwarded to aListener's methods
 205      * @see nsIChannelEventSink for onChannelRedirect
 206      */
 207     void asyncOpen(in nsIStreamListener aListener, in nsISupports aContext);
 208
 209     /**************************************************************************
 210      * Channel specific load flags:
 211      *
 212      * Bits 22-31 are reserved for future use by this interface or one of its
 213      * derivatives (e.g., see nsICachingChannel).
 214      */
 215
 216     /**
 217      * Set (e.g., by the docshell) to indicate whether or not the channel
 218      * corresponds to a document URI.
 219      */
 220     const unsigned long LOAD_DOCUMENT_URI = 1 << 16;
 221
 222     /**
 223      * If the end consumer for this load has been retargeted after discovering
 224      * its content, this flag will be set:
 225      */
 226     const unsigned long LOAD_RETARGETED_DOCUMENT_URI = 1 << 17;
 227
 228     /**
 229      * This flag is set to indicate that this channel is replacing another
 230      * channel.  This means that:
 231      *
 232      * 1) the stream listener this channel will be notifying was initially
 233      *    passed to the asyncOpen method of some other channel
 234      *
 235      *   and
 236      *
 237      * 2) this channel's URI is a better identifier of the resource being
 238      *    accessed than this channel's originalURI.
 239      *
 240      * This flag can be set, for example, for redirects or for cases when a
 241      * single channel has multiple parts to it (and thus can follow
 242      * onStopRequest with another onStartRequest/onStopRequest pair, each pair
 243      * for a different request).
 244      */
 245     const unsigned long LOAD_REPLACE = 1 << 18;
 246
 247     /**
 248      * Set (e.g., by the docshell) to indicate whether or not the channel
 249      * corresponds to an initial document URI load (e.g., link click).
 250      */
 251     const unsigned long LOAD_INITIAL_DOCUMENT_URI = 1 << 19;
 252
 253     /**
 254      * Set (e.g., by the URILoader) to indicate whether or not the end consumer
 255      * for this load has been determined.
 256      */
 257     const unsigned long LOAD_TARGETED = 1 << 20;
 258
 259     /**
 260      * If this flag is set, the channel should call the content sniffers as
 261      * described in nsNetCID.h about NS_CONTENT_SNIFFER_CATEGORY.
 262      *
 263      * Note: Channels may ignore this flag; however, new channel implementations
 264      * should only do so with good reason.
 265      */
 266     const unsigned long LOAD_CALL_CONTENT_SNIFFERS = 1 << 21;
 267 };