1/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2/* This Source Code Form is subject to the terms of the Mozilla Public 3 * License, v. 2.0. If a copy of the MPL was not distributed with this 4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 5 6#include "imgINotificationObserver.idl" 7 8%{C++ 9#include "mozilla/Maybe.h" 10#include "Visibility.h" 11%} 12 13interface imgIRequest; 14interface nsIChannel; 15interface nsIStreamListener; 16interface nsIURI; 17interface nsIFrame; 18 19[ref] native MaybeOnNonvisible(const mozilla::Maybe<mozilla::OnNonvisible>); 20native Visibility(mozilla::Visibility); 21 22/** 23 * This interface represents a content node that loads images. The interface 24 * exists to allow getting information on the images that the content node 25 * loads and to allow registration of observers for the image loads. 26 * 27 * Implementors of this interface should handle all the mechanics of actually 28 * loading an image -- getting the URI, checking with content policies and 29 * the security manager to see whether loading the URI is allowed, performing 30 * the load, firing any DOM events as needed. 31 * 32 * An implementation of this interface may support the concepts of a 33 * "current" image and a "pending" image. If it does, a request to change 34 * the currently loaded image will start a "pending" request which will 35 * become current only when the image is loaded. It is the responsibility of 36 * observers to check which request they are getting notifications for. 37 * 38 * Please make sure to update the MozImageLoadingContent WebIDL 39 * mixin to mirror this interface when changing it. 40 */ 41 42// We can't make this interface noscript yet, because there is JS code doing 43// "instanceof Ci.nsIImageLoadingContent" and using the nsIImageLoadingContent 44// constants. 45[scriptable, builtinclass, uuid(0357123d-9224-4d12-a47e-868c32689777)] 46interface nsIImageLoadingContent : imgINotificationObserver 47{ 48 /** 49 * Request types. Image loading content nodes attempt to do atomic 50 * image changes when the image url is changed. This means that 51 * when the url changes the new image load will start, but the old 52 * image will remain the "current" request until the new image is 53 * fully loaded. At that point, the old "current" request will be 54 * discarded and the "pending" request will become "current". 55 */ 56 const long UNKNOWN_REQUEST = -1; 57 const long CURRENT_REQUEST = 0; 58 const long PENDING_REQUEST = 1; 59 60 /** 61 * setLoadingEnabled is used to enable and disable loading in 62 * situations where loading images is unwanted. Note that enabling 63 * loading will *not* automatically trigger an image load. 64 */ 65 [notxpcom, nostdcall] void setLoadingEnabled(in boolean aEnabled); 66 67 /** 68 * Used to register an image decoder observer. Typically, this will 69 * be a proxy for a frame that wants to paint the image. 70 * Notifications from ongoing image loads will be passed to all 71 * registered observers. Notifications for all request types, 72 * current and pending, will be passed through. 73 * 74 * @param aObserver the observer to register 75 */ 76 [notxpcom, nostdcall] void addNativeObserver(in imgINotificationObserver aObserver); 77 78 /** 79 * Used to unregister an image decoder observer. 80 * 81 * @param aObserver the observer to unregister 82 */ 83 [notxpcom, nostdcall] void removeNativeObserver(in imgINotificationObserver aObserver); 84 85 /** 86 * Accessor to get the image requests 87 * 88 * @param aRequestType a value saying which request is wanted 89 * 90 * @return the imgIRequest object (may be null, even when no error 91 * is thrown) 92 * 93 * @throws NS_ERROR_UNEXPECTED if the request type requested is not 94 * known 95 */ 96 [noscript] imgIRequest getRequest(in long aRequestType); 97 98 /** 99 * Used to notify the image loading content node that a frame has been 100 * created. 101 */ 102 [notxpcom] void frameCreated(in nsIFrame aFrame); 103 104 /** 105 * Used to notify the image loading content node that a frame has been 106 * destroyed. 107 */ 108 [notxpcom] void frameDestroyed(in nsIFrame aFrame); 109 110 /** 111 * Used to find out what type of request one is dealing with (eg 112 * which request got passed through to the imgINotificationObserver 113 * interface of an observer) 114 * 115 * @param aRequest the request whose type we want to know 116 * 117 * @return an enum value saying what type this request is 118 * 119 * @throws NS_ERROR_UNEXPECTED if aRequest is not known 120 */ 121 [noscript] long getRequestType(in imgIRequest aRequest); 122 123 /** 124 * Gets the URI of the current request, if available. 125 * Otherwise, returns the last URI that this content tried to load, or 126 * null if there haven't been any such attempts. 127 */ 128 [noscript, infallible] readonly attribute nsIURI currentURI; 129 130 /** 131 * loadImageWithChannel allows data from an existing channel to be 132 * used as the image data for this content node. 133 * 134 * @param aChannel the channel that will deliver the data 135 * 136 * @return a stream listener to pump the image data into 137 * 138 * @see imgILoader::loadImageWithChannel 139 * 140 * @throws NS_ERROR_NULL_POINTER if aChannel is null 141 */ 142 [noscript] nsIStreamListener loadImageWithChannel(in nsIChannel aChannel); 143 144 /** 145 * Called by layout to announce when the frame associated with this content 146 * has changed its visibility state. 147 * 148 * @param aNewVisibility The new visibility state. 149 * @param aNonvisibleAction A requested action if the frame has become 150 * nonvisible. If Nothing(), no action is 151 * requested. If DISCARD_IMAGES is specified, the 152 * frame is requested to ask any images it's 153 * associated with to discard their surfaces if 154 * possible. 155 */ 156 [noscript, notxpcom] void onVisibilityChange(in Visibility aNewVisibility, 157 in MaybeOnNonvisible aNonvisibleAction); 158}; 159