diff -r 000000000000 -r 6474c204b198 content/base/public/nsIImageLoadingContent.idl --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/content/base/public/nsIImageLoadingContent.idl Wed Dec 31 06:09:35 2014 +0100 @@ -0,0 +1,170 @@ +/* -*- 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. + * + * Observers added in mid-load will not get any notifications they + * missed. We should NOT freeze this interface without considering + * this issue. (It could be that the image status on imgIRequest is + * sufficient, when combined with the imageBlockingStatus information.) + * + * Please make sure to update the MozImageLoadingContent WebIDL + * interface to mirror this interface when changing it. + */ + +[scriptable, builtinclass, uuid(e3968acd-b796-4ca3-aec0-e7f0880f2219)] +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); + + /** + * 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 + * + * @throws NS_ERROR_NOT_AVAILABLE if there is no current URI to reload + */ + void forceReload(); + + /** + * 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); + + /** + * A visible count is stored, if it is non-zero then this image is considered + * visible. These methods increment, decrement, or return the visible coount. + */ + [noscript, notxpcom] void IncrementVisibleCount(); + [noscript, notxpcom] void DecrementVisibleCount(); + [noscript, notxpcom] uint32_t GetVisibleCount(); +};