imgIRequest.idl (9232B)
1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- 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/. */ 6 7 #include "nsISupports.idl" 8 #include "nsIRequest.idl" 9 #include "imgIContainer.idl" 10 11 //interface imgIContainer; 12 interface imgINotificationObserver; 13 interface nsIURI; 14 interface nsIPrincipal; 15 interface nsIReferrerInfo; 16 17 /** 18 * imgIRequest interface 19 * 20 * @author Stuart Parmenter <stuart@mozilla.com> 21 * @version 0.1 22 * @see imagelib2 23 */ 24 [scriptable, builtinclass, uuid(db0a945c-3883-424a-98d0-2ee0523b0255)] 25 interface imgIRequest : nsIRequest 26 { 27 /** 28 * the image container... 29 * @return the image object associated with the request. 30 * @attention NEED DOCS 31 */ 32 readonly attribute imgIContainer image; 33 34 /** 35 * Provider ID for image providers created by this image. 36 */ 37 [infallible] readonly attribute unsigned long providerId; 38 39 /** 40 * The principal for the document that loaded this image. Used when trying to 41 * validate a CORS image load. 42 */ 43 [infallible] readonly attribute nsIPrincipal triggeringPrincipal; 44 45 /** 46 * Bits set in the return value from imageStatus 47 * @name statusflags 48 * 49 * Meanings: 50 * 51 * STATUS_NONE: Nothing to report. 52 * 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. 57 * 58 * STATUS_LOAD_COMPLETE: The data has been fully loaded 59 * to memory, but not necessarily fully decoded. 60 * 61 * STATUS_ERROR: An error occurred loading the image. 62 * 63 * STATUS_FRAME_COMPLETE: The first frame has been 64 * completely decoded. 65 * 66 * STATUS_DECODE_COMPLETE: The whole image has been decoded. 67 * 68 * STATUS_IS_ANIMATED: The image is animated. 69 * 70 * STATUS_HAS_TRANSPARENCY: The image is partially or completely transparent. 71 */ 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 //@} 82 83 /** 84 * Status flags of the STATUS_* variety. 85 */ 86 readonly attribute unsigned long imageStatus; 87 88 /* 89 * Actual error code that generated a STATUS_ERROR imageStatus 90 * (see xpcom/base/ErrorList.h) 91 */ 92 [noscript] readonly attribute nsresult imageErrorCode; 93 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). 98 */ 99 [infallible] readonly attribute nsIURI URI; 100 101 /** 102 * The URI of the resource we ended up loading after all redirects, etc. 103 */ 104 readonly attribute nsIURI finalURI; 105 106 readonly attribute imgINotificationObserver notificationObserver; 107 108 readonly attribute string mimeType; 109 110 /** 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. 115 */ 116 readonly attribute ACString fileName; 117 118 /** 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. 123 */ 124 imgIRequest clone(in imgINotificationObserver aObserver); 125 126 /** 127 * The principal gotten from the channel the image was loaded from. 128 */ 129 readonly attribute nsIPrincipal imagePrincipal; 130 131 /** 132 * true if the loading of the image required cross-origin redirects. 133 */ 134 readonly attribute boolean hadCrossOriginRedirects; 135 136 /** 137 * Whether the request is multipart (ie, multipart/x-mixed-replace) 138 */ 139 readonly attribute boolean multipart; 140 141 /** 142 * The CORS mode that this image was loaded with (a mozilla::CORSMode). 143 */ 144 readonly attribute long CORSMode; 145 146 /** 147 * The referrer that this image was loaded with. 148 */ 149 readonly attribute nsIReferrerInfo referrerInfo; 150 151 /** 152 * Cancels this request as in nsIRequest::Cancel(); further, also nulls out 153 * decoderObserver so it gets no further notifications from us. 154 * 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. 159 */ 160 void cancelAndForgetObserver(in nsresult aStatus); 161 162 /** 163 * Requests a synchronous decode for the image. 164 * 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. 170 */ 171 void startDecoding(in uint32_t aFlags); 172 173 /** 174 * Exactly like startDecoding above except returns whether the current frame 175 * of the image is complete or not. 176 * 177 * @param aFlags Flags of the FLAG_* variety. Only FLAG_ASYNC_NOTIFY 178 * is accepted; all others are ignored. 179 */ 180 [noscript, notxpcom] boolean startDecodingWithResult(in uint32_t aFlags); 181 182 /** 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. 186 * 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. 194 */ 195 [noscript, notxpcom] imgIContainer_DecodeResult requestDecodeWithResult(in uint32_t aFlags); 196 /*%{C++ 197 DecodeResult RequestDecodeWithResult(uint32_t aFlags); 198 %}*/ 199 200 /** 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. 203 */ 204 [noscript, notxpcom] boolean hasDecodedPixels(); 205 206 /** 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. 210 * 211 * If you don't call unlockImage() by the time this imgIRequest goes away, it 212 * will be called for you automatically. 213 * 214 * @see imgIContainer::lockImage for documentation of the underlying call. 215 */ 216 void lockImage(); 217 218 /** 219 * Unlocks an image. 220 * 221 * @see imgIContainer::unlockImage for documentation of the underlying call. 222 */ 223 void unlockImage(); 224 225 /** 226 * If this image is unlocked, discard the image's decoded data. If the image 227 * is locked or is already discarded, do nothing. 228 */ 229 void requestDiscard(); 230 231 /** 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. 235 */ 236 imgIRequest getStaticRequest(); 237 238 /** 239 * Requests that the image animate (if it has an animation). 240 * 241 * @see Image::IncrementAnimationConsumers for documentation of the 242 * underlying call. 243 */ 244 void incrementAnimationConsumers(); 245 246 /** 247 * Tell the image it can forget about a request that the image animate. 248 * 249 * @see Image::DecrementAnimationConsumers for documentation of the 250 * underlying call. 251 */ 252 void decrementAnimationConsumers(); 253 254 /** Returns whether this image is actively animating. */ 255 [infallible] readonly attribute boolean hasAnimationConsumers; 256 257 /** 258 * Request loading priority boost to requested category, each category 259 * of request increases priority only one time. 260 * 261 * CATEGORY_FRAME_INIT: increase priority when the imgRequest is associated 262 * with an nsImageFrame. 263 * 264 * CATEGORY_FRAME_STYLE: increase priority when the imgRequest is for a CSS 265 * background-image, list-style-image, etc. on a ComputedStyle, and a frame 266 * has been assigned this ComputedStyle. 267 * 268 * CATEGORY_SIZE_QUERY: increase priority when size decoding is necessary to 269 * determine the layout size of an associated nsImageFrame. 270 * 271 * CATEGORY_DISPLAY: increase priority when the image is about to be displayed 272 * in the viewport. 273 */ 274 const uint32_t CATEGORY_FRAME_INIT = 1 << 0; 275 const uint32_t CATEGORY_FRAME_STYLE = 1 << 1; 276 const uint32_t CATEGORY_SIZE_QUERY = 1 << 2; 277 const uint32_t CATEGORY_DISPLAY = 1 << 3; 278 void boostPriority(in uint32_t aCategory); 279 };