uriloader/base/nsIURIContentListener.idl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   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 nsIRequest;
  41 interface nsIStreamListener;
  42 interface nsIURI;
  43
  44 /**
  45  * nsIURIContentListener is an interface used by components which
  46  * want to know (and have a chance to handle) a particular content type.
  47  * Typical usage scenarios will include running applications which register
  48  * a nsIURIContentListener for each of its content windows with the uri
  49  * dispatcher service.
  50  *
  51  * @status FROZEN
  52  */
  53 [scriptable, uuid(94928AB3-8B63-11d3-989D-001083010E9B)]
  54 interface nsIURIContentListener : nsISupports
  55 {
  56  /**
  57   * Gives the original content listener first crack at stopping a load before
  58   * it happens.
  59   *
  60   * @param aURI   URI that is being opened.
  61   *
  62   * @return       <code>false</code> if the load can continue;
  63   *               <code>true</code> if the open should be aborted.
  64   */
  65   boolean onStartURIOpen(in nsIURI aURI);
  66
  67  /**
  68   * Notifies the content listener to hook up an nsIStreamListener capable of
  69   * consuming the data stream.
  70   *
  71   * @param aContentType         Content type of the data.
  72   * @param aIsContentPreferred  Indicates whether the content should be
  73   *                             preferred by this listener.
  74   * @param aRequest             Request that is providing the data.
  75   * @param aContentHandler      nsIStreamListener that will consume the data.
  76   *                             This should be set to <code>nsnull</code> if
  77   *                             this content listener can't handle the content
  78   *                             type.
  79   *
  80   * @return                     <code>true</code> if the consumer wants to
  81   *                             handle the load completely by itself.  This
  82   *                             causes the URI Loader do nothing else...
  83   *                             <code>false</code> if the URI Loader should
  84   *                             continue handling the load and call the
  85   *                             returned streamlistener's methods.
  86   */
  87   boolean doContent(in string aContentType,
  88                     in boolean aIsContentPreferred,
  89                     in nsIRequest aRequest,
  90                     out nsIStreamListener aContentHandler);
  91
  92  /**
  93   * When given a uri to dispatch, if the URI is specified as 'preferred
  94   * content' then the uri loader tries to find a preferred content handler
  95   * for the content type. The thought is that many content listeners may
  96   * be able to handle the same content type if they have to. i.e. the mail
  97   * content window can handle text/html just like a browser window content
  98   * listener. However, if the user clicks on a link with text/html content,
  99   * then the browser window should handle that content and not the mail
 100   * window where the user may have clicked the link.  This is the difference
 101   * between isPreferred and canHandleContent.
 102   *
 103   * @param aContentType         Content type of the data.
 104   * @param aDesiredContentType  Indicates that aContentType must be converted
 105   *                             to aDesiredContentType before processing the
 106   *                             data.  This causes a stream converted to be
 107   *                             inserted into the nsIStreamListener chain.
 108   *                             This argument can be <code>nsnull</code> if
 109   *                             the content should be consumed directly as
 110   *                             aContentType.
 111   *
 112   * @return                     <code>true</code> if this is a preferred
 113   *                             content handler for aContentType;
 114   *                             <code>false<code> otherwise.
 115   */
 116   boolean isPreferred(in string aContentType, out string aDesiredContentType);
 117
 118  /**
 119   * When given a uri to dispatch, if the URI is not specified as 'preferred
 120   * content' then the uri loader calls canHandleContent to see if the content
 121   * listener is capable of handling the content.
 122   *
 123   * @param aContentType         Content type of the data.
 124   * @param aIsContentPreferred  Indicates whether the content should be
 125   *                             preferred by this listener.
 126   * @param aDesiredContentType  Indicates that aContentType must be converted
 127   *                             to aDesiredContentType before processing the
 128   *                             data.  This causes a stream converted to be
 129   *                             inserted into the nsIStreamListener chain.
 130   *                             This argument can be <code>nsnull</code> if
 131   *                             the content should be consumed directly as
 132   *                             aContentType.
 133   *
 134   * @return                     <code>true</code> if the data can be consumed.
 135   *                             <code>false</code> otherwise.
 136   *
 137   * Note: I really envision canHandleContent as a method implemented
 138   * by the docshell as the implementation is generic to all doc
 139   * shells. The isPreferred decision is a decision made by a top level
 140   * application content listener that sits at the top of the docshell
 141   * hierarchy.
 142   */
 143   boolean canHandleContent(in string aContentType,
 144                            in boolean aIsContentPreferred,
 145                            out string aDesiredContentType);
 146
 147  /**
 148   * The load context associated with a particular content listener.
 149   * The URI Loader stores and accesses this value as needed.
 150   */
 151   attribute nsISupports loadCookie;
 152
 153  /**
 154   * The parent content listener if this particular listener is part of a chain
 155   * of content listeners (i.e. a docshell!)
 156   *
 157   * @note If this attribute is set to an object that implements
 158   *       nsISupportsWeakReference, the implementation should get the
 159   *       nsIWeakReference and hold that.  Otherwise, the implementation
 160   *       should not refcount this interface; it should assume that a non
 161   *       null value is always valid.  In that case, the caller is
 162   *       responsible for explicitly setting this value back to null if the
 163   *       parent content listener is destroyed.
 164   */
 165   attribute nsIURIContentListener parentContentListener;
 166 };
 167