dom/base/nsIImageLoadingContent.idl

   1 /* -*- Mode: C++; 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 "imgINotificationObserver.idl"
   7
   8 interface imgIRequest;
   9 interface nsIChannel;
  10 interface nsIStreamListener;
  11 interface nsIURI;
  12 interface nsIDocument;
  13 interface nsIFrame;
  14
  15 /**
  16  * This interface represents a content node that loads images.  The interface
  17  * exists to allow getting information on the images that the content node
  18  * loads and to allow registration of observers for the image loads.
  19  *
  20  * Implementors of this interface should handle all the mechanics of actually
  21  * loading an image -- getting the URI, checking with content policies and
  22  * the security manager to see whether loading the URI is allowed, performing
  23  * the load, firing any DOM events as needed.
  24  *
  25  * An implementation of this interface may support the concepts of a
  26  * "current" image and a "pending" image.  If it does, a request to change
  27  * the currently loaded image will start a "pending" request which will
  28  * become current only when the image is loaded.  It is the responsibility of
  29  * observers to check which request they are getting notifications for.
  30  *
  31  * Observers added in mid-load will not get any notifications they
  32  * missed.  We should NOT freeze this interface without considering
  33  * this issue.  (It could be that the image status on imgIRequest is
  34  * sufficient, when combined with the imageBlockingStatus information.)
  35  *
  36  * Please make sure to update the MozImageLoadingContent WebIDL
  37  * interface to mirror this interface when changing it.
  38  */
  39
  40 [scriptable, builtinclass, uuid(5794d12b-3195-4526-a814-a2181f6c71fe)]
  41 interface nsIImageLoadingContent : imgINotificationObserver
  42 {
  43   /**
  44    * Request types.  Image loading content nodes attempt to do atomic
  45    * image changes when the image url is changed.  This means that
  46    * when the url changes the new image load will start, but the old
  47    * image will remain the "current" request until the new image is
  48    * fully loaded.  At that point, the old "current" request will be
  49    * discarded and the "pending" request will become "current".
  50    */
  51   const long UNKNOWN_REQUEST = -1;
  52   const long CURRENT_REQUEST = 0;
  53   const long PENDING_REQUEST = 1;
  54
  55   /**
  56    * loadingEnabled is used to enable and disable loading in
  57    * situations where loading images is unwanted.  Note that enabling
  58    * loading will *not* automatically trigger an image load.
  59    */
  60   attribute boolean loadingEnabled;
  61
  62   /**
  63    * Returns the image blocking status (@see nsIContentPolicy).  This
  64    * will always be an nsIContentPolicy REJECT_* status for cases when
  65    * the image was blocked.  This status always refers to the
  66    * CURRENT_REQUEST load.
  67    */
  68   readonly attribute short imageBlockingStatus;
  69
  70   /**
  71    * Used to register an image decoder observer.  Typically, this will
  72    * be a proxy for a frame that wants to paint the image.
  73    * Notifications from ongoing image loads will be passed to all
  74    * registered observers.  Notifications for all request types,
  75    * current and pending, will be passed through.
  76    *
  77    * @param aObserver the observer to register
  78    *
  79    * @throws NS_ERROR_OUT_OF_MEMORY
  80    */
  81   void addObserver(in imgINotificationObserver aObserver);
  82
  83   /**
  84    * Used to unregister an image decoder observer.
  85    *
  86    * @param aObserver the observer to unregister
  87    */
  88   void removeObserver(in imgINotificationObserver aObserver);
  89
  90   /**
  91    * Accessor to get the image requests
  92    *
  93    * @param aRequestType a value saying which request is wanted
  94    *
  95    * @return the imgIRequest object (may be null, even when no error
  96    * is thrown)
  97    *
  98    * @throws NS_ERROR_UNEXPECTED if the request type requested is not
  99    * known
 100    */
 101   imgIRequest getRequest(in long aRequestType);
 102
 103   /**
 104    * Used to notify the image loading content node that a frame has been
 105    * created.
 106    */
 107   [notxpcom] void frameCreated(in nsIFrame aFrame);
 108
 109   /**
 110    * Used to notify the image loading content node that a frame has been
 111    * destroyed.
 112    */
 113   [notxpcom] void frameDestroyed(in nsIFrame aFrame);
 114
 115   /**
 116    * Used to find out what type of request one is dealing with (eg
 117    * which request got passed through to the imgINotificationObserver
 118    * interface of an observer)
 119    *
 120    * @param aRequest the request whose type we want to know
 121    *
 122    * @return an enum value saying what type this request is
 123    *
 124    * @throws NS_ERROR_UNEXPECTED if aRequest is not known
 125    */
 126   long getRequestType(in imgIRequest aRequest);
 127
 128   /**
 129    * Gets the URI of the current request, if available.
 130    * Otherwise, returns the last URI that this content tried to load, or
 131    * null if there haven't been any such attempts.
 132    */
 133   readonly attribute nsIURI currentURI;
 134
 135   /**
 136    * loadImageWithChannel allows data from an existing channel to be
 137    * used as the image data for this content node.
 138    *
 139    * @param aChannel the channel that will deliver the data
 140    *
 141    * @return a stream listener to pump the image data into
 142    *
 143    * @see imgILoader::loadImageWithChannel
 144    *
 145    * @throws NS_ERROR_NULL_POINTER if aChannel is null
 146    */
 147   nsIStreamListener loadImageWithChannel(in nsIChannel aChannel);
 148
 149   /**
 150    * forceReload forces reloading of the image pointed to by currentURI
 151    *
 152    * @param aNotify [optional] request should notify, defaults to true
 153    * @throws NS_ERROR_NOT_AVAILABLE if there is no current URI to reload
 154    */
 155   [optional_argc] void forceReload([optional] in boolean aNotify /* = true */);
 156
 157   /**
 158    * Enables/disables image state forcing. When |aForce| is PR_TRUE, we force
 159    * nsImageLoadingContent::ImageState() to return |aState|. Call again with |aForce|
 160    * as PR_FALSE to revert ImageState() to its original behaviour.
 161    */
 162   void forceImageState(in boolean aForce, in unsigned long long aState);
 163
 164   /**
 165    * The intrinsic size and width of this content. May differ from actual image
 166    * size due to things like responsive image density.
 167    */
 168   readonly attribute unsigned long    naturalWidth;
 169   readonly attribute unsigned long    naturalHeight;
 170
 171   /**
 172    * A visible count is stored, if it is non-zero then this image is considered
 173    * visible. These methods increment, decrement, or return the visible count.
 174    *
 175    * @param aNonvisibleAction What to do if the image's visibility count is now
 176    *                          zero. If ON_NONVISIBLE_NO_ACTION, nothing will be
 177    *                          done. If ON_NONVISIBLE_REQUEST_DISCARD, the image
 178    *                          will be asked to discard its surfaces if possible.
 179    */
 180   [noscript, notxpcom] void IncrementVisibleCount();
 181   [noscript, notxpcom] void DecrementVisibleCount(in uint32_t aNonvisibleAction);
 182   [noscript, notxpcom] uint32_t GetVisibleCount();
 183
 184   const long ON_NONVISIBLE_NO_ACTION = 0;
 185   const long ON_NONVISIBLE_REQUEST_DISCARD = 1;
 186 };