1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
/* -*- 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"
%{C++
#include "mozilla/Maybe.h"
#include "Visibility.h"
%}
interface imgIRequest;
interface nsIChannel;
interface nsIStreamListener;
interface nsIURI;
interface nsIDocument;
interface nsIFrame;
[ref] native MaybeOnNonvisible(const mozilla::Maybe<mozilla::OnNonvisible>);
native Visibility(mozilla::Visibility);
/**
* 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.
*
* Please make sure to update the MozImageLoadingContent WebIDL
* interface to mirror this interface when changing it.
*/
[scriptable, builtinclass, uuid(0357123d-9224-4d12-a47e-868c32689777)]
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.
*/
[infallible] 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);
/**
* Call this function when the request was blocked by any of the
* security policies enforced.
*
* @param aContentDecision the decision returned from nsIContentPolicy
* (any of the types REJECT_*)
*/
void setBlockedRequest(in int16_t aContentDecision);
/**
* @return true if the current request's size is available.
*/
[noscript, notxpcom] boolean currentRequestHasSize();
/**
* 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
*
* @param aNotify [optional] request should notify, defaults to true
* @throws NS_ERROR_NOT_AVAILABLE if there is no current URI to reload
*/
[optional_argc] void forceReload([optional] in boolean aNotify /* = true */);
/**
* 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);
/**
* The intrinsic size and width of this content. May differ from actual image
* size due to things like responsive image density.
*/
readonly attribute unsigned long naturalWidth;
readonly attribute unsigned long naturalHeight;
/**
* Called by layout to announce when the frame associated with this content
* has changed its visibility state.
*
* @param aNewVisibility The new visibility state.
* @param aNonvisibleAction A requested action if the frame has become
* nonvisible. If Nothing(), no action is
* requested. If DISCARD_IMAGES is specified, the
* frame is requested to ask any images it's
* associated with to discard their surfaces if
* possible.
*/
[noscript, notxpcom] void onVisibilityChange(in Visibility aNewVisibility,
in MaybeOnNonvisible aNonvisibleAction);
};
|
