1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
3 * This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
7 #include
"nsISupports.idl"
8 #include
"nsIRequest.idl"
10 interface imgIContainer
;
11 interface imgINotificationObserver
;
13 interface nsIPrincipal
;
16 * imgIRequest interface
18 * @author Stuart Parmenter <stuart@mozilla.com>
22 [scriptable
, builtinclass
, uuid(db0a945c
-3883-424a
-98d0
-2ee0523b0255
)]
23 interface imgIRequest
: nsIRequest
26 * the image container...
27 * @return the image object associated with the request.
28 * @attention NEED DOCS
30 readonly attribute imgIContainer image
;
33 * Bits set in the return value from imageStatus
38 * STATUS_NONE: Nothing to report.
40 * STATUS_SIZE_AVAILABLE: We received enough image data
41 * from the network or filesystem that we know the width
42 * and height of the image, and have thus called SetSize()
45 * STATUS_LOAD_COMPLETE: The data has been fully loaded
46 * to memory, but not necessarily fully decoded.
48 * STATUS_ERROR: An error occurred loading the image.
50 * STATUS_FRAME_COMPLETE: The first frame has been
53 * STATUS_DECODE_COMPLETE: The whole image has been decoded.
55 * STATUS_IS_ANIMATED: The image is animated.
57 * STATUS_HAS_TRANSPARENCY: The image is partially or completely transparent.
60 const long STATUS_NONE
= 0x0;
61 const long STATUS_SIZE_AVAILABLE
= 0x1;
62 const long STATUS_LOAD_COMPLETE
= 0x2;
63 const long STATUS_ERROR
= 0x4;
64 const long STATUS_FRAME_COMPLETE
= 0x8;
65 const long STATUS_DECODE_COMPLETE
= 0x10;
66 const long STATUS_IS_ANIMATED
= 0x20;
67 const long STATUS_HAS_TRANSPARENCY
= 0x40;
71 * Status flags of the STATUS_* variety.
73 readonly attribute
unsigned long imageStatus
;
76 * Actual error code that generated a STATUS_ERROR imageStatus
77 * (see xpcom/base/ErrorList.h)
79 [noscript
] readonly attribute nsresult imageErrorCode
;
82 * The URI the image load was started with. Note that this might not be the
83 * actual URI for the image (e.g. if HTTP redirects happened during the
86 readonly attribute nsIURI URI
;
89 * The URI of the resource we ended up loading after all redirects, etc.
91 readonly attribute nsIURI finalURI
;
93 readonly attribute imgINotificationObserver notificationObserver
;
95 readonly attribute
string mimeType
;
98 * Clone this request; the returned request will have aObserver as the
99 * observer. aObserver will be notified synchronously (before the clone()
100 * call returns) with all the notifications that have already been dispatched
101 * for this image load.
103 imgIRequest clone
(in imgINotificationObserver aObserver
);
106 * The principal gotten from the channel the image was loaded from.
108 readonly attribute nsIPrincipal imagePrincipal
;
111 * Whether the request is multipart (ie, multipart/x-mixed-replace)
113 readonly attribute bool multipart
;
116 * CORS modes images can be loaded with.
118 * By default, all images are loaded with CORS_NONE and cannot be used
119 * cross-origin in context like WebGL.
121 * If an HTML img element has the crossorigin attribute set, the imgIRequest
122 * will be validated for cross-origin usage with CORS, and, if successful,
123 * will have its CORS mode set to the relevant type.
126 const long CORS_NONE
= 1;
127 const long CORS_ANONYMOUS
= 2;
128 const long CORS_USE_CREDENTIALS
= 3;
132 * The CORS mode that this image was loaded with.
134 readonly attribute
long CORSMode
;
137 * Cancels this request as in nsIRequest::Cancel(); further, also nulls out
138 * decoderObserver so it gets no further notifications from us.
140 * NOTE: You should not use this in any new code; instead, use cancel(). Note
141 * that cancel() is asynchronous, which means that some time after you call
142 * it, the listener/observer will get an OnStopRequest(). This means that, if
143 * you're the observer, you can't call cancel() from your destructor.
145 void cancelAndForgetObserver
(in nsresult aStatus
);
148 * Requests a synchronous decode for the image.
150 * imgIContainer has a startDecoding() method, but callers may want to request
151 * a decode before the container has necessarily been instantiated. Calling
152 * startDecoding() on the imgIRequest simply forwards along the request if the
153 * container already exists, or calls it once the container becomes available
154 * if it does not yet exist.
156 void startDecoding
(in uint32_t aFlags
);
159 * Exactly like startDecoding above except returns whether the current frame
160 * of the image is complete or not.
162 [noscript
, notxpcom
] boolean startDecodingWithResult
(in uint32_t aFlags
);
165 * Locks an image. If the image does not exist yet, locks it once it becomes
166 * available. The lock persists for the lifetime of the imgIRequest (until
167 * unlockImage is called) even if the underlying image changes.
169 * If you don't call unlockImage() by the time this imgIRequest goes away, it
170 * will be called for you automatically.
172 * @see imgIContainer::lockImage for documentation of the underlying call.
179 * @see imgIContainer::unlockImage for documentation of the underlying call.
184 * If this image is unlocked, discard the image's decoded data. If the image
185 * is locked or is already discarded, do nothing.
187 void requestDiscard
();
190 * If this request is for an animated image, the method creates a new
191 * request which contains the current frame of the image.
192 * Otherwise returns the same request.
194 imgIRequest getStaticRequest
();
197 * Requests that the image animate (if it has an animation).
199 * @see Image::IncrementAnimationConsumers for documentation of the
202 void incrementAnimationConsumers
();
205 * Tell the image it can forget about a request that the image animate.
207 * @see Image::DecrementAnimationConsumers for documentation of the
210 void decrementAnimationConsumers
();
213 * Request loading priority boost to requested category, each category
214 * of request increases priority only one time..
216 * CATEGORY_FRAME_INIT: increase priority when the imgRequest is associated
217 * with an nsImageFrame.
219 * CATEGORY_SIZE_QUERY: increase priority when size decoding is necessary to
220 * determine the layout size of the associated nsImageFrame.
222 * CATEGORY_DISPLAY: increase priority when the image is about to be displayed
225 const uint32_t CATEGORY_FRAME_INIT
= 1 << 0;
226 const uint32_t CATEGORY_SIZE_QUERY
= 1 << 1;
227 const uint32_t CATEGORY_DISPLAY
= 1 << 2;
228 void boostPriority
(in uint32_t aCategory
);