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 (b6d82b1a6b02)

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
/* -*- 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"

%{C++
#include "mozilla/Maybe.h"
#include "Visibility.h"
%}

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

[ref] native MaybeOnNonvisible(const mozilla::Maybe<mozilla::OnNonvisible>);
native Visibility(mozilla::Visibility);

/**
 * 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.
 */

// We can't make this interface noscript yet, because there is JS code doing
// "instanceof Ci.nsIImageLoadingContent" and using the nsIImageLoadingContent
// constants.
[scriptable, builtinclass, uuid(0357123d-9224-4d12-a47e-868c32689777)]
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;

  /**
   * setLoadingEnabled 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.
   */
  [notxpcom, nostdcall] void setLoadingEnabled(in boolean aEnabled);

  /**
   * 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.
   */
  [notxpcom, nostdcall] 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
   */
  [notxpcom, nostdcall] void addNativeObserver(in imgINotificationObserver aObserver);

  /**
   * Used to unregister an image decoder observer.
   *
   * @param aObserver the observer to unregister
   */
  [notxpcom, nostdcall] void removeNativeObserver(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
   */
  [noscript] imgIRequest getRequest(in long aRequestType);

  /**
   * Call this function when the request was blocked by any of the
   * security policies enforced.
   *
   * @param aContentDecision the decision returned from nsIContentPolicy
   *                         (any of the types REJECT_*)
   */
  [notxpcom, nostdcall] void setBlockedRequest(in int16_t aContentDecision);

  /**
   * 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
   */
  [noscript] 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.
   */
  [noscript] 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
   */
  [noscript] nsIStreamListener loadImageWithChannel(in nsIChannel aChannel);

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

  /**
   * Called by layout to announce when the frame associated with this content
   * has changed its visibility state.
   *
   * @param aNewVisibility    The new visibility state.
   * @param aNonvisibleAction A requested action if the frame has become
   *                          nonvisible. If Nothing(), no action is
   *                          requested. If DISCARD_IMAGES is specified, the
   *                          frame is requested to ask any images it's
   *                          associated with to discard their surfaces if
   *                          possible.
   */
  [noscript, notxpcom] void onVisibilityChange(in Visibility aNewVisibility,
                                               in MaybeOnNonvisible aNonvisibleAction);
};