uriloader/base/nsIURIContentListener.idl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7
   8 interface nsIRequest;
   9 interface nsIStreamListener;
  10 interface nsIURI;
  11
  12 /**
  13  * nsIURIContentListener is an interface used by components which
  14  * want to know (and have a chance to handle) a particular content type.
  15  * Typical usage scenarios will include running applications which register
  16  * a nsIURIContentListener for each of its content windows with the uri
  17  * dispatcher service.
  18  */
  19 [scriptable, uuid(10a28f38-32e8-4c63-8aa1-12eaaebc369a)]
  20 interface nsIURIContentListener : nsISupports
  21 {
  22  /**
  23   * Notifies the content listener to hook up an nsIStreamListener capable of
  24   * consuming the data stream.
  25   *
  26   * @param aContentType         Content type of the data.
  27   * @param aIsContentPreferred  Indicates whether the content should be
  28   *                             preferred by this listener.
  29   * @param aRequest             Request that is providing the data.
  30   * @param aContentHandler      nsIStreamListener that will consume the data.
  31   *                             This should be set to <code>nullptr</code> if
  32   *                             this content listener can't handle the content
  33   *                             type; in this case, doContent should also fail
  34   *                             (i.e., return failure nsresult).
  35   *
  36   * @return                     <code>true</code> if the load should
  37   *                             be aborted and consumer wants to
  38   *                             handle the load completely by itself.  This
  39   *                             causes the URI Loader do nothing else...
  40   *                             <code>false</code> if the URI Loader should
  41   *                             continue handling the load and call the
  42   *                             returned streamlistener's methods.
  43   */
  44   boolean doContent(in ACString aContentType,
  45                     in boolean aIsContentPreferred,
  46                     in nsIRequest aRequest,
  47                     out nsIStreamListener aContentHandler);
  48
  49  /**
  50   * When given a uri to dispatch, if the URI is specified as 'preferred
  51   * content' then the uri loader tries to find a preferred content handler
  52   * for the content type. The thought is that many content listeners may
  53   * be able to handle the same content type if they have to. i.e. the mail
  54   * content window can handle text/html just like a browser window content
  55   * listener. However, if the user clicks on a link with text/html content,
  56   * then the browser window should handle that content and not the mail
  57   * window where the user may have clicked the link.  This is the difference
  58   * between isPreferred and canHandleContent.
  59   *
  60   * @param aContentType         Content type of the data.
  61   * @param aDesiredContentType  Indicates that aContentType must be converted
  62   *                             to aDesiredContentType before processing the
  63   *                             data.  This causes a stream converted to be
  64   *                             inserted into the nsIStreamListener chain.
  65   *                             This argument can be <code>nullptr</code> if
  66   *                             the content should be consumed directly as
  67   *                             aContentType.
  68   *
  69   * @return                     <code>true</code> if this is a preferred
  70   *                             content handler for aContentType;
  71   *                             <code>false<code> otherwise.
  72   */
  73   boolean isPreferred(in string aContentType, out string aDesiredContentType);
  74
  75  /**
  76   * When given a uri to dispatch, if the URI is not specified as 'preferred
  77   * content' then the uri loader calls canHandleContent to see if the content
  78   * listener is capable of handling the content.
  79   *
  80   * @param aContentType         Content type of the data.
  81   * @param aIsContentPreferred  Indicates whether the content should be
  82   *                             preferred by this listener.
  83   * @param aDesiredContentType  Indicates that aContentType must be converted
  84   *                             to aDesiredContentType before processing the
  85   *                             data.  This causes a stream converted to be
  86   *                             inserted into the nsIStreamListener chain.
  87   *                             This argument can be <code>nullptr</code> if
  88   *                             the content should be consumed directly as
  89   *                             aContentType.
  90   *
  91   * @return                     <code>true</code> if the data can be consumed.
  92   *                             <code>false</code> otherwise.
  93   *
  94   * Note: I really envision canHandleContent as a method implemented
  95   * by the docshell as the implementation is generic to all doc
  96   * shells. The isPreferred decision is a decision made by a top level
  97   * application content listener that sits at the top of the docshell
  98   * hierarchy.
  99   */
 100   boolean canHandleContent(in string aContentType,
 101                            in boolean aIsContentPreferred,
 102                            out string aDesiredContentType);
 103
 104  /**
 105   * The load context associated with a particular content listener.
 106   * The URI Loader stores and accesses this value as needed.
 107   */
 108   attribute nsISupports loadCookie;
 109
 110  /**
 111   * The parent content listener if this particular listener is part of a chain
 112   * of content listeners (i.e. a docshell!)
 113   *
 114   * @note If this attribute is set to an object that implements
 115   *       nsISupportsWeakReference, the implementation should get the
 116   *       nsIWeakReference and hold that.  Otherwise, the implementation
 117   *       should not refcount this interface; it should assume that a non
 118   *       null value is always valid.  In that case, the caller is
 119   *       responsible for explicitly setting this value back to null if the
 120   *       parent content listener is destroyed.
 121   */
 122   attribute nsIURIContentListener parentContentListener;
 123 };