michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "imgINotificationObserver.idl"
michael@0: 
michael@0: interface imgIRequest;
michael@0: interface nsIChannel;
michael@0: interface nsIStreamListener;
michael@0: interface nsIURI;
michael@0: interface nsIDocument;
michael@0: interface nsIFrame;
michael@0: 
michael@0: /**
michael@0:  * This interface represents a content node that loads images.  The interface
michael@0:  * exists to allow getting information on the images that the content node
michael@0:  * loads and to allow registration of observers for the image loads.
michael@0:  *
michael@0:  * Implementors of this interface should handle all the mechanics of actually
michael@0:  * loading an image -- getting the URI, checking with content policies and
michael@0:  * the security manager to see whether loading the URI is allowed, performing
michael@0:  * the load, firing any DOM events as needed.
michael@0:  *
michael@0:  * An implementation of this interface may support the concepts of a
michael@0:  * "current" image and a "pending" image.  If it does, a request to change
michael@0:  * the currently loaded image will start a "pending" request which will
michael@0:  * become current only when the image is loaded.  It is the responsibility of
michael@0:  * observers to check which request they are getting notifications for.
michael@0:  *
michael@0:  * Observers added in mid-load will not get any notifications they
michael@0:  * missed.  We should NOT freeze this interface without considering
michael@0:  * this issue.  (It could be that the image status on imgIRequest is
michael@0:  * sufficient, when combined with the imageBlockingStatus information.)
michael@0:  *
michael@0:  * Please make sure to update the MozImageLoadingContent WebIDL
michael@0:  * interface to mirror this interface when changing it.
michael@0:  */
michael@0: 
michael@0: [scriptable, builtinclass, uuid(e3968acd-b796-4ca3-aec0-e7f0880f2219)]
michael@0: interface nsIImageLoadingContent : imgINotificationObserver
michael@0: {
michael@0:   /**
michael@0:    * Request types.  Image loading content nodes attempt to do atomic
michael@0:    * image changes when the image url is changed.  This means that
michael@0:    * when the url changes the new image load will start, but the old
michael@0:    * image will remain the "current" request until the new image is
michael@0:    * fully loaded.  At that point, the old "current" request will be
michael@0:    * discarded and the "pending" request will become "current".
michael@0:    */
michael@0:   const long UNKNOWN_REQUEST = -1;
michael@0:   const long CURRENT_REQUEST = 0;
michael@0:   const long PENDING_REQUEST = 1;
michael@0: 
michael@0:   /**
michael@0:    * loadingEnabled is used to enable and disable loading in
michael@0:    * situations where loading images is unwanted.  Note that enabling
michael@0:    * loading will *not* automatically trigger an image load.
michael@0:    */
michael@0:   attribute boolean loadingEnabled;
michael@0: 
michael@0:   /**
michael@0:    * Returns the image blocking status (@see nsIContentPolicy).  This
michael@0:    * will always be an nsIContentPolicy REJECT_* status for cases when
michael@0:    * the image was blocked.  This status always refers to the
michael@0:    * CURRENT_REQUEST load.
michael@0:    */
michael@0:   readonly attribute short imageBlockingStatus;
michael@0: 
michael@0:   /**
michael@0:    * Used to register an image decoder observer.  Typically, this will
michael@0:    * be a proxy for a frame that wants to paint the image.
michael@0:    * Notifications from ongoing image loads will be passed to all
michael@0:    * registered observers.  Notifications for all request types,
michael@0:    * current and pending, will be passed through.
michael@0:    *
michael@0:    * @param aObserver the observer to register
michael@0:    *
michael@0:    * @throws NS_ERROR_OUT_OF_MEMORY
michael@0:    */
michael@0:   void addObserver(in imgINotificationObserver aObserver);
michael@0: 
michael@0:   /**
michael@0:    * Used to unregister an image decoder observer.
michael@0:    *
michael@0:    * @param aObserver the observer to unregister
michael@0:    */
michael@0:   void removeObserver(in imgINotificationObserver aObserver);
michael@0:   
michael@0:   /**
michael@0:    * Accessor to get the image requests
michael@0:    *
michael@0:    * @param aRequestType a value saying which request is wanted
michael@0:    *
michael@0:    * @return the imgIRequest object (may be null, even when no error
michael@0:    * is thrown)
michael@0:    *
michael@0:    * @throws NS_ERROR_UNEXPECTED if the request type requested is not
michael@0:    * known
michael@0:    */
michael@0:   imgIRequest getRequest(in long aRequestType);
michael@0: 
michael@0:   /**
michael@0:    * Used to notify the image loading content node that a frame has been
michael@0:    * created.
michael@0:    */
michael@0:   [notxpcom] void frameCreated(in nsIFrame aFrame);
michael@0: 
michael@0:   /**
michael@0:    * Used to notify the image loading content node that a frame has been
michael@0:    * destroyed.
michael@0:    */
michael@0:   [notxpcom] void frameDestroyed(in nsIFrame aFrame);
michael@0: 
michael@0:   /**
michael@0:    * Used to find out what type of request one is dealing with (eg
michael@0:    * which request got passed through to the imgINotificationObserver
michael@0:    * interface of an observer)
michael@0:    *
michael@0:    * @param aRequest the request whose type we want to know
michael@0:    *
michael@0:    * @return an enum value saying what type this request is
michael@0:    *
michael@0:    * @throws NS_ERROR_UNEXPECTED if aRequest is not known
michael@0:    */
michael@0:   long getRequestType(in imgIRequest aRequest);
michael@0: 
michael@0:   /**
michael@0:    * Gets the URI of the current request, if available.
michael@0:    * Otherwise, returns the last URI that this content tried to load, or
michael@0:    * null if there haven't been any such attempts.
michael@0:    */
michael@0:   readonly attribute nsIURI currentURI;
michael@0: 
michael@0:   /**
michael@0:    * loadImageWithChannel allows data from an existing channel to be
michael@0:    * used as the image data for this content node.
michael@0:    *
michael@0:    * @param aChannel the channel that will deliver the data
michael@0:    *
michael@0:    * @return a stream listener to pump the image data into
michael@0:    *
michael@0:    * @see imgILoader::loadImageWithChannel
michael@0:    *
michael@0:    * @throws NS_ERROR_NULL_POINTER if aChannel is null
michael@0:    */
michael@0:   nsIStreamListener loadImageWithChannel(in nsIChannel aChannel);
michael@0: 
michael@0:   /**
michael@0:    * forceReload forces reloading of the image pointed to by currentURI
michael@0:    *
michael@0:    * @throws NS_ERROR_NOT_AVAILABLE if there is no current URI to reload
michael@0:    */
michael@0:   void forceReload();
michael@0: 
michael@0:   /**
michael@0:    * Enables/disables image state forcing. When |aForce| is PR_TRUE, we force
michael@0:    * nsImageLoadingContent::ImageState() to return |aState|. Call again with |aForce|
michael@0:    * as PR_FALSE to revert ImageState() to its original behaviour.
michael@0:    */
michael@0:   void forceImageState(in boolean aForce, in unsigned long long aState);
michael@0: 
michael@0:   /**
michael@0:    * A visible count is stored, if it is non-zero then this image is considered
michael@0:    * visible. These methods increment, decrement, or return the visible coount.
michael@0:    */
michael@0:   [noscript, notxpcom] void IncrementVisibleCount();
michael@0:   [noscript, notxpcom] void DecrementVisibleCount();
michael@0:   [noscript, notxpcom] uint32_t GetVisibleCount();
michael@0: };