pjs/uriloader/base/nsIURIContentListener.idl

/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* ***** 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 ***** */

/**
 *  nsIURIContentListener is an interface used by classes which
 *  want to know (and have a chance to handle) a particular content type.
 *  Typical useage scenarios will include running applications which register
 *  a nsIURIContentListener for each of its content windows with the uri dispatcher
 *  service. 
 * 
 * @status UNDER_REVIEW
 */ 

#include "nsISupports.idl"
#include "nsIURILoader.idl"

interface nsIRequest;
interface nsIStreamListener;
interface nsIURI;

[scriptable, uuid(94928AB3-8B63-11d3-989D-001083010E9B)]
interface nsIURIContentListener : nsISupports
{
  /*
	  Gives the content listener first crack at stopping a load before it
	  happens.
	  
	  aURI --> the uri we are going to try and open.
	  return value --> specifies if the open should be aborted.  
  */
  boolean onStartURIOpen(in nsIURI aURI);

  /* doContent --> When the content listener is expected to process the
     content, the uri loader calls doContent. doContent needs to return a 
	 nsIStreamListener which the uri loader will push the content into. 

     aContentType --> the content type we need to handle
     aCommand --> verb for the action (this comes from layout???)
     aWindowTarget --> name of the target window if any
     aStreamListener --> the content viewer the content should be displayed in
                        You should return null for this out parameter if you do
                        not want to handle this content type.
     return value --> If you want to handle the content yourself and you don't
					   want the dispatcher to do anything else, return
					   TRUE, else return false.
  */

  boolean doContent(in string aContentType, 
                    in nsURILoadCommand aCommand, 
                    in nsIRequest request,
                    out nsIStreamListener aContentHandler);

   /* When given a uri to dispatch, if the load type is a user click,
      then the uri loader tries to find a preferred content handler
      for this content type. The thought is that many content
      listeners may be able to handle the same content type if they
      have to. i.e. the mail content window can handle text/html just
      like a browser window content listener. However, if the user
      clicks on a link with text/html content, we'd like the browser
      window to handle that content and not the mail window where the
      user may have clicked the link. That's why we have isPreferred.
      
      aContentType --> the content type to handle
      aCommand --> verb for the action
      aDesiredContentType --> yes, we can accept aContentType but we would
          like it converted to aDesiredContentType. This argument can
          be null if you want the content directly as aContentType
      boolean --> return true if you are a preferred content handler
                  for aContentType and false otherwise.
   */
   boolean isPreferred(in string aContentType, 
                       in nsURILoadCommand aCommand,
                       out string aDesiredContentType);

   /* When given a uri to dispatch, if the load type is anything but
      user click, the uri loader will call canHandleContent to see if
      the content listener can handle the content. The arguments are
      the same as isPreferred.

      Note: I really envision canHandleContent as a method implemented
      by the docshell as the implementation is generic to all doc
      shells. The IsPreferred decision is a decision made by a top level
      application content listener that sits at the top of the docshell
      hiearchy.
   */
  boolean canHandleContent(in string aContentType, 
                           in nsURILoadCommand aCommand, 
                           out string aDesiredContentType);
  
  /* Get/Set loadCookie are methods the uri loader calls on the
   *  nsIURIContentListener in order to store / associate a load context
   *  with this particular content listener...
   */
  attribute nsISupports loadCookie;
  /* if you are part of a chain of content listeners (i.e. if you are
   * a docshell!) return your parent content listener
   */
  attribute nsIURIContentListener parentContentListener;
};