Bug 1890277: part 1) Add CSP parser tests for `require-trusted-types-for`. r=tschuster
[gecko.git] / image / imgIRequest.idl
blob9db2a0069e8be0eb4894424c964c92debfcf4edb
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"
9 #include "imgIContainer.idl"
11 //interface imgIContainer;
12 interface imgINotificationObserver;
13 interface nsIURI;
14 interface nsIPrincipal;
15 interface nsIReferrerInfo;
17 /**
18 * imgIRequest interface
20 * @author Stuart Parmenter <stuart@mozilla.com>
21 * @version 0.1
22 * @see imagelib2
24 [scriptable, builtinclass, uuid(db0a945c-3883-424a-98d0-2ee0523b0255)]
25 interface imgIRequest : nsIRequest
27 /**
28 * the image container...
29 * @return the image object associated with the request.
30 * @attention NEED DOCS
32 readonly attribute imgIContainer image;
34 /**
35 * Provider ID for image providers created by this image.
37 [infallible] readonly attribute unsigned long providerId;
39 /**
40 * The principal for the document that loaded this image. Used when trying to
41 * validate a CORS image load.
43 [infallible] readonly attribute nsIPrincipal triggeringPrincipal;
45 /**
46 * Bits set in the return value from imageStatus
47 * @name statusflags
49 * Meanings:
51 * STATUS_NONE: Nothing to report.
53 * STATUS_SIZE_AVAILABLE: We received enough image data
54 * from the network or filesystem that we know the width
55 * and height of the image, and have thus called SetSize()
56 * on the container.
58 * STATUS_LOAD_COMPLETE: The data has been fully loaded
59 * to memory, but not necessarily fully decoded.
61 * STATUS_ERROR: An error occurred loading the image.
63 * STATUS_FRAME_COMPLETE: The first frame has been
64 * completely decoded.
66 * STATUS_DECODE_COMPLETE: The whole image has been decoded.
68 * STATUS_IS_ANIMATED: The image is animated.
70 * STATUS_HAS_TRANSPARENCY: The image is partially or completely transparent.
72 //@{
73 const long STATUS_NONE = 0x0;
74 const long STATUS_SIZE_AVAILABLE = 0x1;
75 const long STATUS_LOAD_COMPLETE = 0x2;
76 const long STATUS_ERROR = 0x4;
77 const long STATUS_FRAME_COMPLETE = 0x8;
78 const long STATUS_DECODE_COMPLETE = 0x10;
79 const long STATUS_IS_ANIMATED = 0x20;
80 const long STATUS_HAS_TRANSPARENCY = 0x40;
81 //@}
83 /**
84 * Status flags of the STATUS_* variety.
86 readonly attribute unsigned long imageStatus;
89 * Actual error code that generated a STATUS_ERROR imageStatus
90 * (see xpcom/base/ErrorList.h)
92 [noscript] readonly attribute nsresult imageErrorCode;
94 /**
95 * The URI the image load was started with. Note that this might not be the
96 * actual URI for the image (e.g. if HTTP redirects happened during the
97 * load).
99 [infallible] readonly attribute nsIURI URI;
102 * The URI of the resource we ended up loading after all redirects, etc.
104 readonly attribute nsIURI finalURI;
106 readonly attribute imgINotificationObserver notificationObserver;
108 readonly attribute string mimeType;
111 * The filename that should be used when saving the image. This is determined
112 * from the Content-Disposition, if present, or the uri of the image. This
113 * filename should be validated using nsIMIMEService::GetValidFilenameForSaving
114 * before creating the file.
116 readonly attribute ACString fileName;
119 * Clone this request; the returned request will have aObserver as the
120 * observer. aObserver will be notified synchronously (before the clone()
121 * call returns) with all the notifications that have already been dispatched
122 * for this image load.
124 imgIRequest clone(in imgINotificationObserver aObserver);
127 * The principal gotten from the channel the image was loaded from.
129 readonly attribute nsIPrincipal imagePrincipal;
132 * true if the loading of the image required cross-origin redirects.
134 readonly attribute boolean hadCrossOriginRedirects;
137 * Whether the request is multipart (ie, multipart/x-mixed-replace)
139 readonly attribute boolean multipart;
142 * The CORS mode that this image was loaded with (a mozilla::CORSMode).
144 readonly attribute long CORSMode;
147 * The referrer that this image was loaded with.
149 readonly attribute nsIReferrerInfo referrerInfo;
152 * Cancels this request as in nsIRequest::Cancel(); further, also nulls out
153 * decoderObserver so it gets no further notifications from us.
155 * NOTE: You should not use this in any new code; instead, use cancel(). Note
156 * that cancel() is asynchronous, which means that some time after you call
157 * it, the listener/observer will get an OnStopRequest(). This means that, if
158 * you're the observer, you can't call cancel() from your destructor.
160 void cancelAndForgetObserver(in nsresult aStatus);
163 * Requests a synchronous decode for the image.
165 * imgIContainer has a startDecoding() method, but callers may want to request
166 * a decode before the container has necessarily been instantiated. Calling
167 * startDecoding() on the imgIRequest simply forwards along the request if the
168 * container already exists, or calls it once the container becomes available
169 * if it does not yet exist.
171 void startDecoding(in uint32_t aFlags);
174 * Exactly like startDecoding above except returns whether the current frame
175 * of the image is complete or not.
177 * @param aFlags Flags of the FLAG_* variety. Only FLAG_ASYNC_NOTIFY
178 * is accepted; all others are ignored.
180 [noscript, notxpcom] boolean startDecodingWithResult(in uint32_t aFlags);
183 * This method triggers decoding for an image, but unlike startDecoding() it
184 * enables the caller to provide more detailed information about the decode
185 * request.
187 * @param aFlags Flags of the FLAG_* variety.
188 * @return DECODE_SURFACE_AVAILABLE if is a surface that satisfies the
189 * request and it is fully decoded.
190 * DECODE_REQUESTED if we requested a decode.
191 * DECODE_REQUEST_FAILED if we failed to request a decode. This means
192 * that either there is an error in the image or we cannot allocate a
193 * surface that big.
195 [noscript, notxpcom] imgIContainer_DecodeResult requestDecodeWithResult(in uint32_t aFlags);
196 /*%{C++
197 DecodeResult RequestDecodeWithResult(uint32_t aFlags);
198 %}*/
201 * Returns true if there is a image and the image has a frame and the frame
202 * currently has a least 1 decoded pixel. Only valid for raster images.
204 [noscript, notxpcom] boolean hasDecodedPixels();
207 * Locks an image. If the image does not exist yet, locks it once it becomes
208 * available. The lock persists for the lifetime of the imgIRequest (until
209 * unlockImage is called) even if the underlying image changes.
211 * If you don't call unlockImage() by the time this imgIRequest goes away, it
212 * will be called for you automatically.
214 * @see imgIContainer::lockImage for documentation of the underlying call.
216 void lockImage();
219 * Unlocks an image.
221 * @see imgIContainer::unlockImage for documentation of the underlying call.
223 void unlockImage();
226 * If this image is unlocked, discard the image's decoded data. If the image
227 * is locked or is already discarded, do nothing.
229 void requestDiscard();
232 * If this request is for an animated image, the method creates a new
233 * request which contains the current frame of the image.
234 * Otherwise returns the same request.
236 imgIRequest getStaticRequest();
239 * Requests that the image animate (if it has an animation).
241 * @see Image::IncrementAnimationConsumers for documentation of the
242 * underlying call.
244 void incrementAnimationConsumers();
247 * Tell the image it can forget about a request that the image animate.
249 * @see Image::DecrementAnimationConsumers for documentation of the
250 * underlying call.
252 void decrementAnimationConsumers();
255 * Request loading priority boost to requested category, each category
256 * of request increases priority only one time.
258 * CATEGORY_FRAME_INIT: increase priority when the imgRequest is associated
259 * with an nsImageFrame.
261 * CATEGORY_FRAME_STYLE: increase priority when the imgRequest is for a CSS
262 * background-image, list-style-image, etc. on a ComputedStyle, and a frame
263 * has been assigned this ComputedStyle.
265 * CATEGORY_SIZE_QUERY: increase priority when size decoding is necessary to
266 * determine the layout size of an associated nsImageFrame.
268 * CATEGORY_DISPLAY: increase priority when the image is about to be displayed
269 * in the viewport.
271 const uint32_t CATEGORY_FRAME_INIT = 1 << 0;
272 const uint32_t CATEGORY_FRAME_STYLE = 1 << 1;
273 const uint32_t CATEGORY_SIZE_QUERY = 1 << 2;
274 const uint32_t CATEGORY_DISPLAY = 1 << 3;
275 void boostPriority(in uint32_t aCategory);