content/base/public/nsIImageLoadingContent.idl@6474c204b198
content/base/public/nsIImageLoadingContent.idl
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
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/. */
6 #include "imgINotificationObserver.idl"
8 interface imgIRequest;
9 interface nsIChannel;
10 interface nsIStreamListener;
11 interface nsIURI;
12 interface nsIDocument;
13 interface nsIFrame;
15 /**
16 * This interface represents a content node that loads images. The interface
17 * exists to allow getting information on the images that the content node
18 * loads and to allow registration of observers for the image loads.
19 *
20 * Implementors of this interface should handle all the mechanics of actually
21 * loading an image -- getting the URI, checking with content policies and
22 * the security manager to see whether loading the URI is allowed, performing
23 * the load, firing any DOM events as needed.
24 *
25 * An implementation of this interface may support the concepts of a
26 * "current" image and a "pending" image. If it does, a request to change
27 * the currently loaded image will start a "pending" request which will
28 * become current only when the image is loaded. It is the responsibility of
29 * observers to check which request they are getting notifications for.
30 *
31 * Observers added in mid-load will not get any notifications they
32 * missed. We should NOT freeze this interface without considering
33 * this issue. (It could be that the image status on imgIRequest is
34 * sufficient, when combined with the imageBlockingStatus information.)
35 *
36 * Please make sure to update the MozImageLoadingContent WebIDL
37 * interface to mirror this interface when changing it.
38 */
40 [scriptable, builtinclass, uuid(e3968acd-b796-4ca3-aec0-e7f0880f2219)]
41 interface nsIImageLoadingContent : imgINotificationObserver
42 {
43 /**
44 * Request types. Image loading content nodes attempt to do atomic
45 * image changes when the image url is changed. This means that
46 * when the url changes the new image load will start, but the old
47 * image will remain the "current" request until the new image is
48 * fully loaded. At that point, the old "current" request will be
49 * discarded and the "pending" request will become "current".
50 */
51 const long UNKNOWN_REQUEST = -1;
52 const long CURRENT_REQUEST = 0;
53 const long PENDING_REQUEST = 1;
55 /**
56 * loadingEnabled is used to enable and disable loading in
57 * situations where loading images is unwanted. Note that enabling
58 * loading will *not* automatically trigger an image load.
59 */
60 attribute boolean loadingEnabled;
62 /**
63 * Returns the image blocking status (@see nsIContentPolicy). This
64 * will always be an nsIContentPolicy REJECT_* status for cases when
65 * the image was blocked. This status always refers to the
66 * CURRENT_REQUEST load.
67 */
68 readonly attribute short imageBlockingStatus;
70 /**
71 * Used to register an image decoder observer. Typically, this will
72 * be a proxy for a frame that wants to paint the image.
73 * Notifications from ongoing image loads will be passed to all
74 * registered observers. Notifications for all request types,
75 * current and pending, will be passed through.
76 *
77 * @param aObserver the observer to register
78 *
79 * @throws NS_ERROR_OUT_OF_MEMORY
80 */
81 void addObserver(in imgINotificationObserver aObserver);
83 /**
84 * Used to unregister an image decoder observer.
85 *
86 * @param aObserver the observer to unregister
87 */
88 void removeObserver(in imgINotificationObserver aObserver);
90 /**
91 * Accessor to get the image requests
92 *
93 * @param aRequestType a value saying which request is wanted
94 *
95 * @return the imgIRequest object (may be null, even when no error
96 * is thrown)
97 *
98 * @throws NS_ERROR_UNEXPECTED if the request type requested is not
99 * known
100 */
101 imgIRequest getRequest(in long aRequestType);
103 /**
104 * Used to notify the image loading content node that a frame has been
105 * created.
106 */
107 [notxpcom] void frameCreated(in nsIFrame aFrame);
109 /**
110 * Used to notify the image loading content node that a frame has been
111 * destroyed.
112 */
113 [notxpcom] void frameDestroyed(in nsIFrame aFrame);
115 /**
116 * Used to find out what type of request one is dealing with (eg
117 * which request got passed through to the imgINotificationObserver
118 * interface of an observer)
119 *
120 * @param aRequest the request whose type we want to know
121 *
122 * @return an enum value saying what type this request is
123 *
124 * @throws NS_ERROR_UNEXPECTED if aRequest is not known
125 */
126 long getRequestType(in imgIRequest aRequest);
128 /**
129 * Gets the URI of the current request, if available.
130 * Otherwise, returns the last URI that this content tried to load, or
131 * null if there haven't been any such attempts.
132 */
133 readonly attribute nsIURI currentURI;
135 /**
136 * loadImageWithChannel allows data from an existing channel to be
137 * used as the image data for this content node.
138 *
139 * @param aChannel the channel that will deliver the data
140 *
141 * @return a stream listener to pump the image data into
142 *
143 * @see imgILoader::loadImageWithChannel
144 *
145 * @throws NS_ERROR_NULL_POINTER if aChannel is null
146 */
147 nsIStreamListener loadImageWithChannel(in nsIChannel aChannel);
149 /**
150 * forceReload forces reloading of the image pointed to by currentURI
151 *
152 * @throws NS_ERROR_NOT_AVAILABLE if there is no current URI to reload
153 */
154 void forceReload();
156 /**
157 * Enables/disables image state forcing. When |aForce| is PR_TRUE, we force
158 * nsImageLoadingContent::ImageState() to return |aState|. Call again with |aForce|
159 * as PR_FALSE to revert ImageState() to its original behaviour.
160 */
161 void forceImageState(in boolean aForce, in unsigned long long aState);
163 /**
164 * A visible count is stored, if it is non-zero then this image is considered
165 * visible. These methods increment, decrement, or return the visible coount.
166 */
167 [noscript, notxpcom] void IncrementVisibleCount();
168 [noscript, notxpcom] void DecrementVisibleCount();
169 [noscript, notxpcom] uint32_t GetVisibleCount();
170 };
