image/imgIRequest.idl

   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 bool hadCrossOriginRedirects;
 135
 136   /**
 137    * Whether the request is multipart (ie, multipart/x-mixed-replace)
 138    */
 139   readonly attribute bool 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   /**
 255    * Request loading priority boost to requested category, each category
 256    * of request increases priority only one time.
 257    *
 258    * CATEGORY_FRAME_INIT: increase priority when the imgRequest is associated
 259    * with an nsImageFrame.
 260    *
 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.
 264    *
 265    * CATEGORY_SIZE_QUERY: increase priority when size decoding is necessary to
 266    * determine the layout size of an associated nsImageFrame.
 267    *
 268    * CATEGORY_DISPLAY: increase priority when the image is about to be displayed
 269    * in the viewport.
 270    */
 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);
 276 };