gecko-dev/uriloader/base/nsIURILoader.idl

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * 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 Netscape are
 * Copyright (C) 1999 Netscape Communications Corporation. All
 * Rights Reserved.
 *
 * Contributor(s): 
 */

/* 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 nsIStreamObserver;
interface nsIURI;
interface nsILoadGroup;
interface nsIEventSinkGetter;
interface nsIChannel;

[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 -> the verb that comes from layout... (can be null)
	 aWindowTarget -> the name of the desired target window (can be null)
	 aEventSinkGetter -> the event sink associated with the url
	 aLoadGroup -> a load group you want the url to go into when we open it
	 aContext -> the context associated with the url (can be null)
     aContentListener --> a content listener you want to give first crack
                          at handling the uri. (can be null) 
     aContext --> same context for the AsyncOpen call that you would have passed
                  if you were calling nsIIOChannel::AsyncOpen
     aReferringURI --> if a uri referral was involved....
  */ 
  void openURI(in nsIURI aURI, in string aCommand, in string aWindowTarget,
			   in nsIEventSinkGetter aEventSinkGetter, 
               in nsILoadGroup aLoadGroup,
               in nsISupports aContext,
               in nsIURIContentListener aContentListener,
               in nsIURI aReferringURI);

  /* 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 nsIURI aURI, in string aCommand, in string aWindowTarget,
				  in nsIEventSinkGetter aEventSinkGetter,
				  in nsILoadGroup aLoadGroup,
				  in nsISupports aContext,
				  in nsIURIContentListener aContentListener,
				  in nsIURI aReferringURI,
				  in unsigned long adapterBinding); 

  void dispatchContent(in string aContentType,
					   in string aCommand,
					   in string aWindowTarget,
					   in nsIChannel aChannel, 
					   in nsISupports aCtxt,
					   in nsIURIContentListener aContentListener);
};