uriloader/base/nsIURILoader.idl

   1 /* -*- Mode: C++; tab-width: 2; 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) 1999
  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 of the GNU General Public License Version 2 or later (the "GPL"),
  26  * or 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 "nsISupports.idl"
  39
  40 interface nsIURIContentListener;
  41 interface nsIURI;
  42 interface nsILoadGroup;
  43 interface nsIProgressEventSink;
  44 interface nsIChannel;
  45 interface nsIRequest;
  46 interface nsIStreamListener;
  47 interface nsIInputStream;
  48 interface nsIInterfaceRequestor;
  49
  50 /**
  51  * The uri dispatcher is responsible for taking uri's, determining
  52  * the content and routing the opened url to the correct content
  53  * handler.
  54  *
  55  * When you encounter a url you want to open, you typically call
  56  * openURI, passing it the content listener for the window the uri is
  57  * originating from. The uri dispatcher opens the url to discover the
  58  * content type. It then gives the content listener first crack at
  59  * handling the content. If it doesn't want it, the dispatcher tries
  60  * to hand it off one of the registered content listeners. This allows
  61  * running applications the chance to jump in and handle the content.
  62  *
  63  * If that also fails, then the uri dispatcher goes to the registry
  64  * looking for the preferred content handler for the content type
  65  * of the uri. The content handler may create an app instance
  66  * or it may hand the contents off to a platform specific plugin
  67  * or helper app. Or it may hand the url off to an OS registered
  68  * application.
  69  */
  70 [scriptable, uuid(2f7e8051-f1c9-4bcc-8584-9cfd5849e343)]
  71 interface nsIURILoader : nsISupports
  72 {
  73   /**
  74    * @name Flags for opening URIs.
  75    */
  76   /* @{ */
  77   /**
  78    * Should the content be displayed in a container that prefers the
  79    * content-type, or will any container do.
  80    */
  81   const unsigned long IS_CONTENT_PREFERRED = 1 << 0;
  82   /**
  83    * If this flag is set, only the listener of the specified window context will
  84    * be considered for content handling; if it refuses the load, an error will
  85    * be indicated.
  86    */
  87   const unsigned long DONT_RETARGET        = 1 << 1;
  88   /* @} */
  89
  90   /**
  91    * As applications such as messenger and the browser are instantiated,
  92    * they register content listener's with the uri dispatcher corresponding
  93    * to content windows within that application.
  94    *
  95    * Note to self: we may want to optimize things a bit more by requiring
  96    * the content types the registered content listener cares about.
  97    *
  98    * @param aContentListener
  99    *        The listener to register. This listener must implement
 100    *        nsISupportsWeakReference.
 101    *
 102    * @see the nsIURILoader class description
 103    */
 104   void registerContentListener   (in nsIURIContentListener aContentListener);
 105   void unRegisterContentListener (in nsIURIContentListener aContentListener);
 106
 107   /**
 108    * OpenURI requires the following parameters.....
 109    * @param aChannel
 110    *        The channel that should be opened. This must not be asyncOpen'd yet!
 111    *        If a loadgroup is set on the channel, it will get replaced with a
 112    *        different one.
 113    * @param aIsContentPreferred
 114    *        Should the content be displayed in a container that prefers the
 115    *        content-type, or will any container do.
 116    * @param aWindowContext
 117    *        If you are running the url from a doc shell or a web shell, this is
 118    *        your window context. If you have a content listener you want to
 119    *        give first crack to, the uri loader needs to be able to get it
 120    *        from the window context. We will also be using the window context
 121    *        to get at the progress event sink interface.
 122    *        <b>Must not be null!</b>
 123    */
 124   void openURI(in nsIChannel aChannel,
 125                in boolean aIsContentPreferred,
 126                in nsIInterfaceRequestor aWindowContext);
 127
 128   /**
 129    * Loads data from a channel. This differs from openURI in that the channel
 130    * may already be opened, and that it returns a stream listener into which the
 131    * caller should pump data. The caller is responsible for opening the channel
 132    * and pumping the channel's data into the returned stream listener.
 133    *
 134    * Note: If the channel already has a loadgroup, it will be replaced with the
 135    * window context's load group, or null if the context doesn't have one.
 136    *
 137    * If the window context's nsIURIContentListener refuses the load immediately
 138    * (e.g. in nsIURIContentListener::onStartURIOpen), this method will return
 139    * NS_ERROR_WONT_HANDLE_CONTENT. At that point, the caller should probably
 140    * cancel the channel if it's already open (this method will not cancel the
 141    * channel).
 142    *
 143    * If flags include DONT_RETARGET, and the content listener refuses the load
 144    * during onStartRequest (e.g. in canHandleContent/isPreferred), then the
 145    * returned stream listener's onStartRequest method will return
 146    * NS_ERROR_WONT_HANDLE_CONTENT.
 147    *
 148    * @param aChannel
 149    *        The channel that should be loaded. The channel may already be
 150    *        opened. It must not be closed (i.e. this must be called before the
 151    *        channel calls onStopRequest on its stream listener).
 152    * @param aFlags
 153    *        Combination (bitwise OR) of the flags specified above. 0 indicates
 154    *        default handling.
 155    * @param aWindowContext
 156    *        If you are running the url from a doc shell or a web shell, this is
 157    *        your window context. If you have a content listener you want to
 158    *        give first crack to, the uri loader needs to be able to get it
 159    *        from the window context. We will also be using the window context
 160    *        to get at the progress event sink interface.
 161    *        <b>Must not be null!</b>
 162    */
 163   nsIStreamListener openChannel(in nsIChannel aChannel,
 164                                 in unsigned long aFlags,
 165                                 in nsIInterfaceRequestor aWindowContext);
 166
 167   /**
 168    * Stops an in progress load
 169    */
 170   void stop(in nsISupports aLoadCookie);
 171 };
 172