1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/content/base/public/nsIImageLoadingContent.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,170 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "imgINotificationObserver.idl"
1.10 +
1.11 +interface imgIRequest;
1.12 +interface nsIChannel;
1.13 +interface nsIStreamListener;
1.14 +interface nsIURI;
1.15 +interface nsIDocument;
1.16 +interface nsIFrame;
1.17 +
1.18 +/**
1.19 + * This interface represents a content node that loads images. The interface
1.20 + * exists to allow getting information on the images that the content node
1.21 + * loads and to allow registration of observers for the image loads.
1.22 + *
1.23 + * Implementors of this interface should handle all the mechanics of actually
1.24 + * loading an image -- getting the URI, checking with content policies and
1.25 + * the security manager to see whether loading the URI is allowed, performing
1.26 + * the load, firing any DOM events as needed.
1.27 + *
1.28 + * An implementation of this interface may support the concepts of a
1.29 + * "current" image and a "pending" image. If it does, a request to change
1.30 + * the currently loaded image will start a "pending" request which will
1.31 + * become current only when the image is loaded. It is the responsibility of
1.32 + * observers to check which request they are getting notifications for.
1.33 + *
1.34 + * Observers added in mid-load will not get any notifications they
1.35 + * missed. We should NOT freeze this interface without considering
1.36 + * this issue. (It could be that the image status on imgIRequest is
1.37 + * sufficient, when combined with the imageBlockingStatus information.)
1.38 + *
1.39 + * Please make sure to update the MozImageLoadingContent WebIDL
1.40 + * interface to mirror this interface when changing it.
1.41 + */
1.42 +
1.43 +[scriptable, builtinclass, uuid(e3968acd-b796-4ca3-aec0-e7f0880f2219)]
1.44 +interface nsIImageLoadingContent : imgINotificationObserver
1.45 +{
1.46 + /**
1.47 + * Request types. Image loading content nodes attempt to do atomic
1.48 + * image changes when the image url is changed. This means that
1.49 + * when the url changes the new image load will start, but the old
1.50 + * image will remain the "current" request until the new image is
1.51 + * fully loaded. At that point, the old "current" request will be
1.52 + * discarded and the "pending" request will become "current".
1.53 + */
1.54 + const long UNKNOWN_REQUEST = -1;
1.55 + const long CURRENT_REQUEST = 0;
1.56 + const long PENDING_REQUEST = 1;
1.57 +
1.58 + /**
1.59 + * loadingEnabled is used to enable and disable loading in
1.60 + * situations where loading images is unwanted. Note that enabling
1.61 + * loading will *not* automatically trigger an image load.
1.62 + */
1.63 + attribute boolean loadingEnabled;
1.64 +
1.65 + /**
1.66 + * Returns the image blocking status (@see nsIContentPolicy). This
1.67 + * will always be an nsIContentPolicy REJECT_* status for cases when
1.68 + * the image was blocked. This status always refers to the
1.69 + * CURRENT_REQUEST load.
1.70 + */
1.71 + readonly attribute short imageBlockingStatus;
1.72 +
1.73 + /**
1.74 + * Used to register an image decoder observer. Typically, this will
1.75 + * be a proxy for a frame that wants to paint the image.
1.76 + * Notifications from ongoing image loads will be passed to all
1.77 + * registered observers. Notifications for all request types,
1.78 + * current and pending, will be passed through.
1.79 + *
1.80 + * @param aObserver the observer to register
1.81 + *
1.82 + * @throws NS_ERROR_OUT_OF_MEMORY
1.83 + */
1.84 + void addObserver(in imgINotificationObserver aObserver);
1.85 +
1.86 + /**
1.87 + * Used to unregister an image decoder observer.
1.88 + *
1.89 + * @param aObserver the observer to unregister
1.90 + */
1.91 + void removeObserver(in imgINotificationObserver aObserver);
1.92 +
1.93 + /**
1.94 + * Accessor to get the image requests
1.95 + *
1.96 + * @param aRequestType a value saying which request is wanted
1.97 + *
1.98 + * @return the imgIRequest object (may be null, even when no error
1.99 + * is thrown)
1.100 + *
1.101 + * @throws NS_ERROR_UNEXPECTED if the request type requested is not
1.102 + * known
1.103 + */
1.104 + imgIRequest getRequest(in long aRequestType);
1.105 +
1.106 + /**
1.107 + * Used to notify the image loading content node that a frame has been
1.108 + * created.
1.109 + */
1.110 + [notxpcom] void frameCreated(in nsIFrame aFrame);
1.111 +
1.112 + /**
1.113 + * Used to notify the image loading content node that a frame has been
1.114 + * destroyed.
1.115 + */
1.116 + [notxpcom] void frameDestroyed(in nsIFrame aFrame);
1.117 +
1.118 + /**
1.119 + * Used to find out what type of request one is dealing with (eg
1.120 + * which request got passed through to the imgINotificationObserver
1.121 + * interface of an observer)
1.122 + *
1.123 + * @param aRequest the request whose type we want to know
1.124 + *
1.125 + * @return an enum value saying what type this request is
1.126 + *
1.127 + * @throws NS_ERROR_UNEXPECTED if aRequest is not known
1.128 + */
1.129 + long getRequestType(in imgIRequest aRequest);
1.130 +
1.131 + /**
1.132 + * Gets the URI of the current request, if available.
1.133 + * Otherwise, returns the last URI that this content tried to load, or
1.134 + * null if there haven't been any such attempts.
1.135 + */
1.136 + readonly attribute nsIURI currentURI;
1.137 +
1.138 + /**
1.139 + * loadImageWithChannel allows data from an existing channel to be
1.140 + * used as the image data for this content node.
1.141 + *
1.142 + * @param aChannel the channel that will deliver the data
1.143 + *
1.144 + * @return a stream listener to pump the image data into
1.145 + *
1.146 + * @see imgILoader::loadImageWithChannel
1.147 + *
1.148 + * @throws NS_ERROR_NULL_POINTER if aChannel is null
1.149 + */
1.150 + nsIStreamListener loadImageWithChannel(in nsIChannel aChannel);
1.151 +
1.152 + /**
1.153 + * forceReload forces reloading of the image pointed to by currentURI
1.154 + *
1.155 + * @throws NS_ERROR_NOT_AVAILABLE if there is no current URI to reload
1.156 + */
1.157 + void forceReload();
1.158 +
1.159 + /**
1.160 + * Enables/disables image state forcing. When |aForce| is PR_TRUE, we force
1.161 + * nsImageLoadingContent::ImageState() to return |aState|. Call again with |aForce|
1.162 + * as PR_FALSE to revert ImageState() to its original behaviour.
1.163 + */
1.164 + void forceImageState(in boolean aForce, in unsigned long long aState);
1.165 +
1.166 + /**
1.167 + * A visible count is stored, if it is non-zero then this image is considered
1.168 + * visible. These methods increment, decrement, or return the visible coount.
1.169 + */
1.170 + [noscript, notxpcom] void IncrementVisibleCount();
1.171 + [noscript, notxpcom] void DecrementVisibleCount();
1.172 + [noscript, notxpcom] uint32_t GetVisibleCount();
1.173 +};
