DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (4a108e94d3e2)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "imgINotificationObserver.idl"

interface imgIRequest;
interface nsIChannel;
interface nsIStreamListener;
interface nsIURI;
interface nsIDocument;
interface nsIFrame;

/**
 * This interface represents a content node that loads images.  The interface
 * exists to allow getting information on the images that the content node
 * loads and to allow registration of observers for the image loads.
 *
 * Implementors of this interface should handle all the mechanics of actually
 * loading an image -- getting the URI, checking with content policies and
 * the security manager to see whether loading the URI is allowed, performing
 * the load, firing any DOM events as needed.
 *
 * An implementation of this interface may support the concepts of a
 * "current" image and a "pending" image.  If it does, a request to change
 * the currently loaded image will start a "pending" request which will
 * become current only when the image is loaded.  It is the responsibility of
 * observers to check which request they are getting notifications for.
 *
 * Please make sure to update the MozImageLoadingContent WebIDL
 * interface to mirror this interface when changing it.
 */

[scriptable, builtinclass, uuid(770f7d84-c917-42d7-bf8d-d1b70649e733)]
interface nsIImageLoadingContent : imgINotificationObserver
{
  /**
   * Request types.  Image loading content nodes attempt to do atomic
   * image changes when the image url is changed.  This means that
   * when the url changes the new image load will start, but the old
   * image will remain the "current" request until the new image is
   * fully loaded.  At that point, the old "current" request will be
   * discarded and the "pending" request will become "current".
   */
  const long UNKNOWN_REQUEST = -1;
  const long CURRENT_REQUEST = 0;
  const long PENDING_REQUEST = 1;

  /**
   * loadingEnabled is used to enable and disable loading in
   * situations where loading images is unwanted.  Note that enabling
   * loading will *not* automatically trigger an image load.
   */
  attribute boolean loadingEnabled;

  /**
   * Returns the image blocking status (@see nsIContentPolicy).  This
   * will always be an nsIContentPolicy REJECT_* status for cases when
   * the image was blocked.  This status always refers to the
   * CURRENT_REQUEST load.
   */
  readonly attribute short imageBlockingStatus;

  /**
   * Used to register an image decoder observer.  Typically, this will
   * be a proxy for a frame that wants to paint the image.
   * Notifications from ongoing image loads will be passed to all
   * registered observers.  Notifications for all request types,
   * current and pending, will be passed through.
   *
   * @param aObserver the observer to register
   *
   * @throws NS_ERROR_OUT_OF_MEMORY
   */
  void addObserver(in imgINotificationObserver aObserver);

  /**
   * Used to unregister an image decoder observer.
   *
   * @param aObserver the observer to unregister
   */
  void removeObserver(in imgINotificationObserver aObserver);
  
  /**
   * Accessor to get the image requests
   *
   * @param aRequestType a value saying which request is wanted
   *
   * @return the imgIRequest object (may be null, even when no error
   * is thrown)
   *
   * @throws NS_ERROR_UNEXPECTED if the request type requested is not
   * known
   */
  imgIRequest getRequest(in long aRequestType);

  /**
   * @return true if the current request's size is available.
   */
  [noscript, notxpcom] boolean currentRequestHasSize();

  /**
   * Used to notify the image loading content node that a frame has been
   * created.
   */
  [notxpcom] void frameCreated(in nsIFrame aFrame);

  /**
   * Used to notify the image loading content node that a frame has been
   * destroyed.
   */
  [notxpcom] void frameDestroyed(in nsIFrame aFrame);

  /**
   * Used to find out what type of request one is dealing with (eg
   * which request got passed through to the imgINotificationObserver
   * interface of an observer)
   *
   * @param aRequest the request whose type we want to know
   *
   * @return an enum value saying what type this request is
   *
   * @throws NS_ERROR_UNEXPECTED if aRequest is not known
   */
  long getRequestType(in imgIRequest aRequest);

  /**
   * Gets the URI of the current request, if available.
   * Otherwise, returns the last URI that this content tried to load, or
   * null if there haven't been any such attempts.
   */
  readonly attribute nsIURI currentURI;

  /**
   * loadImageWithChannel allows data from an existing channel to be
   * used as the image data for this content node.
   *
   * @param aChannel the channel that will deliver the data
   *
   * @return a stream listener to pump the image data into
   *
   * @see imgILoader::loadImageWithChannel
   *
   * @throws NS_ERROR_NULL_POINTER if aChannel is null
   */
  nsIStreamListener loadImageWithChannel(in nsIChannel aChannel);

  /**
   * forceReload forces reloading of the image pointed to by currentURI
   *
   * @param aNotify [optional] request should notify, defaults to true
   * @throws NS_ERROR_NOT_AVAILABLE if there is no current URI to reload
   */
  [optional_argc] void forceReload([optional] in boolean aNotify /* = true */);

  /**
   * Enables/disables image state forcing. When |aForce| is PR_TRUE, we force
   * nsImageLoadingContent::ImageState() to return |aState|. Call again with |aForce|
   * as PR_FALSE to revert ImageState() to its original behaviour.
   */
  void forceImageState(in boolean aForce, in unsigned long long aState);

  /**
   * The intrinsic size and width of this content. May differ from actual image
   * size due to things like responsive image density.
   */
  readonly attribute unsigned long    naturalWidth;
  readonly attribute unsigned long    naturalHeight;

  /**
   * A visible count is stored, if it is non-zero then this image is considered
   * visible. These methods increment, decrement, or return the visible count.
   *
   * @param aNonvisibleAction What to do if the image's visibility count is now
   *                          zero. If ON_NONVISIBLE_NO_ACTION, nothing will be
   *                          done. If ON_NONVISIBLE_REQUEST_DISCARD, the image
   *                          will be asked to discard its surfaces if possible.
   */
  [noscript, notxpcom] void IncrementVisibleCount();
  [noscript, notxpcom] void DecrementVisibleCount(in uint32_t aNonvisibleAction);
  [noscript, notxpcom] uint32_t GetVisibleCount();

  const long ON_NONVISIBLE_NO_ACTION = 0;
  const long ON_NONVISIBLE_REQUEST_DISCARD = 1;
};