gecko-dev/uriloader/base/nsIURILoader.idl

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: NPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Netscape 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/NPL/
 *
 * 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.org code.
 *
 * The Initial Developer of the Original Code is 
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 1999
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *
 * 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 NPL, 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 NPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

/* The uri dispatcher is responsible for taking uri's, determining
   the content and routing the opened url to the correct content 
   handler. 

  When you encounter a url you want to open, you typically call 
  openURI, passing it the content listener for the window the uri is 
  originating from. The uri dispatcher opens the url to discover the 
  content type. It then gives the content listener first crack at 
  handling the content. If it doesn't want it, the dispatcher tries
  to hand it off one of the registered content listeners. This allows
  running applications the chance to jump in and handle the content.

  If that also fails, then the uri dispatcher goes to the registry
  looking for the preferred content handler for the content type
  of the uri. The content handler may create an app instance
  or it may hand the contents off to a platform specific plugin
  or helper app. Or it may hand the url off to an OS registered 
  application. 
*/

#include "nsISupports.idl"

interface nsIURIContentListener;
interface nsIURI;
interface nsILoadGroup;
interface nsIDocumentLoader;
interface nsIProgressEventSink;
interface nsIChannel;
interface nsIRequest;
interface nsIStreamListener;
interface nsIInputStream;

[scriptable, uuid(40AECB53-8B65-11d3-989D-001083010E9B)]
interface nsIURILoader : nsISupports
{
  /* as applications such as messenger and the browser are instantiated,
     they register content listener's with the uri dispatcher corresponding
     to content windows within that application. 

     Note to self: we may want to optimize things a bit more by requiring
     the content types the registered content listener cares about.
  */
  void registerContentListener   (in nsIURIContentListener aContentListener);
  void unRegisterContentListener (in nsIURIContentListener aContentListener);

  /* OpenURI requires the following parameters.....
     aURI --> the uri you wish to open
     aCommand --> should the content be displayed in a container that prefers
                  the content-type, or will any container do...
     aWindowContext --> if you are running the url from a doc shell or a
                        web shell, this is your window context. If you have a
                        content listener you want to give first crack to, the
                        uri loader needs to be able to get it from the window
                        context (we'll use nsIInterfaceRequestor).  we will
                        also be using nsIInterfaceRequestor to get at the
                        progress event sink interface.
  */ 

  void openURI(in nsIChannel aChannel,
               in boolean aIsContentPreferred,
               in nsISupports aWindowContext);


  /* same call as OpenURI except this one takes an IP address to use as well...
     adapterBinding -> the local IP address to bind to
   */

  void openURIVia(in nsIChannel aChannel,
                  in boolean aIsContentPreferred,
                  in nsISupports aWindowContext,
                  in unsigned long adapterBinding); 

  /* stops an in progress load
   */
  void stop(in nsISupports aLoadCookie);
  
  /* dirty little back door for sneaking the load group out in case you need 
     it to create the channel before calling openURI
   */
  nsILoadGroup getLoadGroupForContext(in nsISupports aWindowContext);
  nsIDocumentLoader getDocumentLoaderForContext (in nsISupports aWindowContext);


  /* mscott -> I'm going to move this out into a separate private interface
   */
  void dispatchContent(in string aContentType,
                       in boolean aIsContentPreferred,
                       in nsIRequest aRequest, 
                       in nsISupports aCtxt,
                       in nsIURIContentListener aContentListener,
                       in nsISupports aSrcWindowContext,
                       out string aDesiredContentType,
                       out nsIURIContentListener aTargetListener,
                       out boolean abortDispatch);
};