dom/base/nsImageLoadingContent.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   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 /*
   8  * A base class which implements nsIImageLoadingContent and can be
   9  * subclassed by various content nodes that want to provide image
  10  * loading functionality (eg <img>, <object>, etc).
  11  */
  12
  13 #ifndef nsImageLoadingContent_h__
  14 #define nsImageLoadingContent_h__
  15
  16 #include "imgINotificationObserver.h"
  17 #include "mozilla/CORSMode.h"
  18 #include "mozilla/TimeStamp.h"
  19 #include "nsCOMPtr.h"
  20 #include "nsIContentPolicy.h"
  21 #include "nsIImageLoadingContent.h"
  22 #include "nsIRequest.h"
  23 #include "mozilla/dom/BindingDeclarations.h"
  24 #include "mozilla/dom/Promise.h"
  25 #include "mozilla/dom/RustTypes.h"
  26 #include "nsAttrValue.h"
  27 #include "Units.h"
  28
  29 class nsINode;
  30 class nsIURI;
  31 class nsPresContext;
  32 class nsIContent;
  33 class imgRequestProxy;
  34
  35 namespace mozilla {
  36 class AsyncEventDispatcher;
  37 class ErrorResult;
  38
  39 namespace dom {
  40 struct BindContext;
  41 class Document;
  42 class Element;
  43 enum class FetchPriority : uint8_t;
  44 }  // namespace dom
  45 }  // namespace mozilla
  46
  47 #ifdef LoadImage
  48 // Undefine LoadImage to prevent naming conflict with Windows.
  49 #  undef LoadImage
  50 #endif
  51
  52 class nsImageLoadingContent : public nsIImageLoadingContent {
  53  protected:
  54   template <typename T>
  55   using Maybe = mozilla::Maybe<T>;
  56   using Nothing = mozilla::Nothing;
  57   using OnNonvisible = mozilla::OnNonvisible;
  58   using Visibility = mozilla::Visibility;
  59
  60   /* METHODS */
  61  public:
  62   nsImageLoadingContent();
  63   virtual ~nsImageLoadingContent();
  64
  65   NS_DECL_IMGINOTIFICATIONOBSERVER
  66   NS_DECL_NSIIMAGELOADINGCONTENT
  67
  68   // Web IDL binding methods.
  69   // Note that the XPCOM SetLoadingEnabled method is OK for Web IDL bindings
  70   // to use as well, since it does not throw when called via the Web IDL
  71   // bindings.
  72
  73   bool LoadingEnabled() const { return mLoadingEnabled; }
  74   void AddObserver(imgINotificationObserver* aObserver);
  75   void RemoveObserver(imgINotificationObserver* aObserver);
  76   already_AddRefed<imgIRequest> GetRequest(int32_t aRequestType,
  77                                            mozilla::ErrorResult& aError);
  78   int32_t GetRequestType(imgIRequest* aRequest, mozilla::ErrorResult& aError);
  79   already_AddRefed<nsIURI> GetCurrentURI();
  80   already_AddRefed<nsIURI> GetCurrentRequestFinalURI();
  81   void ForceReload(bool aNotify, mozilla::ErrorResult& aError);
  82
  83   mozilla::dom::Element* FindImageMap();
  84   static mozilla::dom::Element* FindImageMap(mozilla::dom::Element*);
  85
  86   /**
  87    * Toggle whether or not to synchronously decode an image on draw.
  88    */
  89   void SetSyncDecodingHint(bool aHint);
  90
  91   /**
  92    * Notify us that the document state has changed. Called by nsDocument so that
  93    * we may reject any promises which require the document to be active.
  94    */
  95   void NotifyOwnerDocumentActivityChanged();
  96
  97   // Trigger text recognition for the current image request.
  98   already_AddRefed<mozilla::dom::Promise> RecognizeCurrentImageText(
  99       mozilla::ErrorResult&);
 100
 101  protected:
 102   enum ImageLoadType {
 103     // Most normal image loads
 104     eImageLoadType_Normal,
 105     // From a <img srcset> or <picture> context. Affects type given to content
 106     // policy.
 107     eImageLoadType_Imageset
 108   };
 109
 110   /**
 111    * LoadImage is called by subclasses when the appropriate
 112    * attributes (eg 'src' for <img> tags) change.  The string passed
 113    * in is the new uri string; this consolidates the code for getting
 114    * the charset, constructing URI objects, and any other incidentals
 115    * into this superclass.
 116    *
 117    * @param aNewURI the URI spec to be loaded (may be a relative URI)
 118    * @param aForce If true, make sure to load the URI.  If false, only
 119    *        load if the URI is different from the currently loaded URI.
 120    * @param aNotify If true, nsIDocumentObserver state change notifications
 121    *                will be sent as needed.
 122    * @param aImageLoadType The ImageLoadType for this request
 123    * @param aTriggeringPrincipal Optional parameter specifying the triggering
 124    *        principal to use for the image load
 125    */
 126   nsresult LoadImage(const nsAString& aNewURI, bool aForce, bool aNotify,
 127                      ImageLoadType aImageLoadType,
 128                      nsIPrincipal* aTriggeringPrincipal = nullptr);
 129
 130   /**
 131    * ImageState is called by subclasses that are computing their content state.
 132    * The return value will have the ElementState::BROKEN bit set as needed.
 133    *
 134    * Note that this state assumes that this node is "trying" to be an
 135    * image (so for example complete lack of attempt to load an image will lead
 136    * to ElementState::BROKEN being set).  Subclasses that are not "trying" to
 137    * be an image (eg an HTML <input> of type other than "image") should just
 138    * not call this method when computing their intrinsic state.
 139    */
 140   mozilla::dom::ElementState ImageState() const;
 141
 142   /**
 143    * LoadImage is called by subclasses when the appropriate
 144    * attributes (eg 'src' for <img> tags) change. If callers have an
 145    * URI object already available, they should use this method.
 146    *
 147    * @param aNewURI the URI to be loaded
 148    * @param aForce If true, make sure to load the URI.  If false, only
 149    *        load if the URI is different from the currently loaded URI.
 150    * @param aNotify If true, nsIDocumentObserver state change notifications
 151    *                will be sent as needed.
 152    * @param aImageLoadType The ImageLoadType for this request
 153    * @param aDocument Optional parameter giving the document this node is in.
 154    *        This is purely a performance optimization.
 155    * @param aLoadFlags Optional parameter specifying load flags to use for
 156    *        the image load
 157    * @param aTriggeringPrincipal Optional parameter specifying the triggering
 158    *        principal to use for the image load
 159    */
 160   nsresult LoadImage(nsIURI* aNewURI, bool aForce, bool aNotify,
 161                      ImageLoadType aImageLoadType, nsLoadFlags aLoadFlags,
 162                      mozilla::dom::Document* aDocument = nullptr,
 163                      nsIPrincipal* aTriggeringPrincipal = nullptr);
 164
 165   nsresult LoadImage(nsIURI* aNewURI, bool aForce, bool aNotify,
 166                      ImageLoadType aImageLoadType,
 167                      nsIPrincipal* aTriggeringPrincipal) {
 168     return LoadImage(aNewURI, aForce, aNotify, aImageLoadType, LoadFlags(),
 169                      nullptr, aTriggeringPrincipal);
 170   }
 171
 172   /**
 173    * helpers to get the document for this content (from the nodeinfo
 174    * and such).  Not named GetOwnerDoc/GetCurrentDoc to prevent ambiguous
 175    * method names in subclasses
 176    *
 177    * @return the document we belong to
 178    */
 179   mozilla::dom::Document* GetOurOwnerDoc();
 180   mozilla::dom::Document* GetOurCurrentDoc();
 181
 182   /**
 183    * Helper function to get the frame associated with this content. Not named
 184    * GetPrimaryFrame to prevent ambiguous method names in subclasses.
 185    *
 186    * @return The frame we own, or nullptr if it doesn't exist, or isn't
 187    * associated with any of our requests.
 188    */
 189   nsIFrame* GetOurPrimaryImageFrame();
 190
 191   /**
 192    * Helper function to get the PresContext associated with this content's
 193    * frame. Not named GetPresContext to prevent ambiguous method names in
 194    * subclasses.
 195    *
 196    * @return The nsPresContext associated with our frame, or nullptr if either
 197    *         the frame doesn't exist, or the frame's prescontext doesn't exist.
 198    */
 199   nsPresContext* GetFramePresContext();
 200
 201   /**
 202    * CancelImageRequests is called by subclasses when they want to
 203    * cancel all image requests (for example when the subclass is
 204    * somehow not an image anymore).
 205    */
 206   void CancelImageRequests(bool aNotify);
 207
 208   /**
 209    * Derived classes of nsImageLoadingContent MUST call Destroy from their
 210    * destructor, or earlier.  It does things that cannot be done in
 211    * ~nsImageLoadingContent because they rely on being able to QueryInterface to
 212    * other derived classes, which cannot happen once the derived class
 213    * destructor has started calling the base class destructors.
 214    */
 215   void Destroy();
 216
 217   /**
 218    * Returns the CORS mode that will be used for all future image loads. The
 219    * default implementation returns CORS_NONE unconditionally.
 220    */
 221   virtual mozilla::CORSMode GetCORSMode();
 222
 223   // Subclasses are *required* to call BindToTree/UnbindFromTree.
 224   void BindToTree(mozilla::dom::BindContext&, nsINode& aParent);
 225   void UnbindFromTree();
 226
 227   void OnLoadComplete(imgIRequest* aRequest, nsresult aStatus);
 228   void OnUnlockedDraw();
 229   void OnImageIsAnimated(imgIRequest* aRequest);
 230
 231   // The nsContentPolicyType we would use for this ImageLoadType
 232   static nsContentPolicyType PolicyTypeForLoad(ImageLoadType aImageLoadType);
 233
 234   void AsyncEventRunning(mozilla::AsyncEventDispatcher* aEvent);
 235
 236   // Get ourselves as an nsIContent*.  Not const because some of the callers
 237   // want a non-const nsIContent.
 238   virtual nsIContent* AsContent() = 0;
 239
 240   virtual mozilla::dom::FetchPriority GetFetchPriorityForImage() const;
 241
 242   /**
 243    * Get width and height of the current request, using given image request if
 244    * attributes are unset.
 245    */
 246   MOZ_CAN_RUN_SCRIPT mozilla::CSSIntSize GetWidthHeightForImage();
 247
 248   /**
 249    * Create a promise and queue a microtask which will ensure the current
 250    * request (after any pending loads are applied) has requested a full decode.
 251    * The promise is fulfilled once the request has a fully decoded surface that
 252    * is available for drawing, or an error condition occurrs (e.g. broken image,
 253    * current request is updated, etc).
 254    *
 255    * https://html.spec.whatwg.org/multipage/embedded-content.html#dom-img-decode
 256    */
 257   already_AddRefed<mozilla::dom::Promise> QueueDecodeAsync(
 258       mozilla::ErrorResult& aRv);
 259
 260   enum class ImageDecodingType : uint8_t {
 261     Auto,
 262     Async,
 263     Sync,
 264   };
 265
 266   static const nsAttrValue::EnumTable kDecodingTable[];
 267   static const nsAttrValue::EnumTable* kDecodingTableDefault;
 268
 269  private:
 270   /**
 271    * Enqueue and/or fulfill a promise created by QueueDecodeAsync.
 272    */
 273   void DecodeAsync(RefPtr<mozilla::dom::Promise>&& aPromise,
 274                    uint32_t aRequestGeneration);
 275
 276   /**
 277    * Attempt to resolve all queued promises based on the state of the current
 278    * request. If the current request does not yet have all of the encoded data,
 279    * or the decoding has not yet completed, it will return without changing the
 280    * promise states.
 281    */
 282   void MaybeResolveDecodePromises();
 283
 284   /**
 285    * Reject all queued promises with the given status.
 286    */
 287   void RejectDecodePromises(nsresult aStatus);
 288
 289   /**
 290    * Age the generation counter if we have a new current request with a
 291    * different URI. If the generation counter is aged, then all queued promises
 292    * will also be rejected.
 293    */
 294   void MaybeAgeRequestGeneration(nsIURI* aNewURI);
 295
 296   /**
 297    * Deregister as an observer for the owner document's activity notifications
 298    * if we have no outstanding decode promises.
 299    */
 300   void MaybeDeregisterActivityObserver();
 301
 302   /**
 303    * Struct used to manage the native image observers.
 304    */
 305   struct ImageObserver {
 306     explicit ImageObserver(imgINotificationObserver* aObserver);
 307     ~ImageObserver();
 308
 309     nsCOMPtr<imgINotificationObserver> mObserver;
 310     ImageObserver* mNext;
 311   };
 312
 313   /**
 314    * Struct used to manage the scripted/XPCOM image observers.
 315    */
 316   class ScriptedImageObserver final {
 317    public:
 318     NS_INLINE_DECL_REFCOUNTING(ScriptedImageObserver)
 319
 320     ScriptedImageObserver(imgINotificationObserver* aObserver,
 321                           RefPtr<imgRequestProxy>&& aCurrentRequest,
 322                           RefPtr<imgRequestProxy>&& aPendingRequest);
 323     bool CancelRequests();
 324
 325     nsCOMPtr<imgINotificationObserver> mObserver;
 326     RefPtr<imgRequestProxy> mCurrentRequest;
 327     RefPtr<imgRequestProxy> mPendingRequest;
 328
 329    private:
 330     ~ScriptedImageObserver();
 331   };
 332
 333   /**
 334    * Struct to report state changes
 335    */
 336   struct AutoStateChanger {
 337     AutoStateChanger(nsImageLoadingContent* aImageContent, bool aNotify)
 338         : mImageContent(aImageContent), mNotify(aNotify) {
 339       mImageContent->mStateChangerDepth++;
 340     }
 341     ~AutoStateChanger() {
 342       mImageContent->mStateChangerDepth--;
 343       mImageContent->UpdateImageState(mNotify);
 344     }
 345
 346     nsImageLoadingContent* mImageContent;
 347     bool mNotify;
 348   };
 349
 350   friend struct AutoStateChanger;
 351
 352   /**
 353    * Method to fire an event once we know what's going on with the image load.
 354    *
 355    * @param aEventType "load", or "error" depending on how things went
 356    * @param aIsCancelable true if event is cancelable.
 357    */
 358   nsresult FireEvent(const nsAString& aEventType, bool aIsCancelable = false);
 359
 360   /**
 361    * Method to cancel and null-out pending event if they exist.
 362    */
 363   void CancelPendingEvent();
 364
 365   RefPtr<mozilla::AsyncEventDispatcher> mPendingEvent;
 366
 367  protected:
 368   /**
 369    * UpdateImageState recomputes the current state of this image loading
 370    * content and updates what ImageState() returns accordingly.  It will also
 371    * fire a ContentStatesChanged() notification as needed if aNotify is true.
 372    */
 373   void UpdateImageState(bool aNotify);
 374
 375   /**
 376    * Method to create an nsIURI object from the given string (will
 377    * handle getting the right charset, base, etc).  You MUST pass in a
 378    * non-null document to this function.
 379    *
 380    * @param aSpec the string spec (from an HTML attribute, eg)
 381    * @param aDocument the document we belong to
 382    * @return the URI we want to be loading
 383    */
 384   nsresult StringToURI(const nsAString& aSpec,
 385                        mozilla::dom::Document* aDocument, nsIURI** aURI);
 386
 387   /**
 388    * Prepare and returns a reference to the "next request". If there's already
 389    * a _usable_ current request (one with SIZE_AVAILABLE), this request is
 390    * "pending" until it becomes usable. Otherwise, this becomes the current
 391    * request.
 392    *
 393    * @param aImageLoadType The ImageLoadType for this request
 394    */
 395   RefPtr<imgRequestProxy>& PrepareNextRequest(ImageLoadType aImageLoadType);
 396
 397   /**
 398    * Returns a COMPtr reference to the current/pending image requests, cleaning
 399    * up and canceling anything that was there before. Note that if you just want
 400    * to get rid of one of the requests, you should call
 401    * Clear*Request(NS_BINDING_ABORTED) instead.
 402    *
 403    * @param aImageLoadType The ImageLoadType for this request
 404    */
 405   RefPtr<imgRequestProxy>& PrepareCurrentRequest(ImageLoadType aImageLoadType);
 406   RefPtr<imgRequestProxy>& PreparePendingRequest(ImageLoadType aImageLoadType);
 407
 408   /**
 409    * Switch our pending request to be our current request.
 410    * mPendingRequest must be non-null!
 411    */
 412   void MakePendingRequestCurrent();
 413
 414   /**
 415    * Cancels and nulls-out the "current" and "pending" requests if they exist.
 416    *
 417    * @param aNonvisibleAction An action to take if the image is no longer
 418    *                          visible as a result; see |UntrackImage|.
 419    */
 420   void ClearCurrentRequest(
 421       nsresult aReason,
 422       const Maybe<OnNonvisible>& aNonvisibleAction = Nothing());
 423   void ClearPendingRequest(
 424       nsresult aReason,
 425       const Maybe<OnNonvisible>& aNonvisibleAction = Nothing());
 426
 427   /**
 428    * Reset animation of the current request if
 429    * |mNewRequestsWillNeedAnimationReset| was true when the request was
 430    * prepared.
 431    */
 432   void ResetAnimationIfNeeded();
 433
 434   /**
 435    * Static helper method to tell us if we have the size of a request. The
 436    * image may be null.
 437    */
 438   static bool HaveSize(imgIRequest* aImage);
 439
 440   /**
 441    * Adds/Removes a given imgIRequest from our document's tracker.
 442    *
 443    * No-op if aImage is null.
 444    *
 445    * @param aFrame If called from FrameCreated the frame passed to FrameCreated.
 446    *               This is our frame, but at the time of the FrameCreated call
 447    *               our primary frame pointer hasn't been set yet, so this is
 448    *               only way to get our frame.
 449    *
 450    * @param aNonvisibleAction A requested action if the frame has become
 451    *                          nonvisible. If Nothing(), no action is
 452    *                          requested. If DISCARD_IMAGES is specified, the
 453    *                          frame is requested to ask any images it's
 454    *                          associated with to discard their surfaces if
 455    *                          possible.
 456    */
 457   void TrackImage(imgIRequest* aImage, nsIFrame* aFrame = nullptr);
 458   void UntrackImage(imgIRequest* aImage,
 459                     const Maybe<OnNonvisible>& aNonvisibleAction = Nothing());
 460
 461   nsLoadFlags LoadFlags();
 462
 463   /* MEMBERS */
 464   RefPtr<imgRequestProxy> mCurrentRequest;
 465   RefPtr<imgRequestProxy> mPendingRequest;
 466   uint8_t mCurrentRequestFlags = 0;
 467   uint8_t mPendingRequestFlags = 0;
 468
 469   enum {
 470     // Set if the request needs ResetAnimation called on it.
 471     REQUEST_NEEDS_ANIMATION_RESET = 1 << 0,
 472     // Set if the request is currently tracked with the document.
 473     REQUEST_IS_TRACKED = 1 << 1,
 474     // Set if this is an imageset request, such as from <img srcset> or
 475     // <picture>
 476     REQUEST_IS_IMAGESET = 1 << 2,
 477   };
 478
 479   // If the image was blocked or if there was an error loading, it's nice to
 480   // still keep track of what the URI was despite not having an imgIRequest.
 481   // We only maintain this in those situations (in the common case, this is
 482   // always null).
 483   nsCOMPtr<nsIURI> mCurrentURI;
 484
 485  private:
 486   /**
 487    * Clones the given "current" or "pending" request for each scripted observer.
 488    */
 489   void CloneScriptedRequests(imgRequestProxy* aRequest);
 490
 491   /**
 492    * Cancels and nulls-out the "current" or "pending" requests if they exist
 493    * for each scripted observer.
 494    */
 495   void ClearScriptedRequests(int32_t aRequestType, nsresult aReason);
 496
 497   /**
 498    * Moves the "pending" request into the "current" request for each scripted
 499    * observer. If there is an existing "current" request, it will cancel it
 500    * first.
 501    */
 502   void MakePendingScriptedRequestsCurrent();
 503
 504   /**
 505    * Depending on the configured decoding hint, and/or how recently we updated
 506    * the image request, force or stop the frame from decoding the image
 507    * synchronously when it is drawn.
 508    * @param aPrepareNextRequest True if this is when updating the image request.
 509    * @param aFrame If called from FrameCreated the frame passed to FrameCreated.
 510    *               This is our frame, but at the time of the FrameCreated call
 511    *               our primary frame pointer hasn't been set yet, so this is
 512    *               only way to get our frame.
 513    */
 514   void MaybeForceSyncDecoding(bool aPrepareNextRequest,
 515                               nsIFrame* aFrame = nullptr);
 516
 517   /**
 518    * Typically we will have only one observer (our frame in the screen
 519    * prescontext), so we want to only make space for one and to
 520    * heap-allocate anything past that (saves memory and malloc churn
 521    * in the common case).  The storage is a linked list, we just
 522    * happen to actually hold the first observer instead of a pointer
 523    * to it.
 524    */
 525   ImageObserver mObserverList;
 526
 527   /**
 528    * Typically we will have no scripted observers, as this is only used by
 529    * chrome, legacy extensions, and some mochitests. An empty array reserves
 530    * minimal memory.
 531    */
 532   nsTArray<RefPtr<ScriptedImageObserver>> mScriptedObservers;
 533
 534   /**
 535    * Promises created by QueueDecodeAsync that are still waiting to be
 536    * fulfilled by the image being fully decoded.
 537    */
 538   nsTArray<RefPtr<mozilla::dom::Promise>> mDecodePromises;
 539
 540   mozilla::TimeStamp mMostRecentRequestChange;
 541
 542   /**
 543    * Total number of outstanding decode promises, including those stored in
 544    * mDecodePromises and those embedded in runnables waiting to be enqueued.
 545    * This is used to determine whether we need to register as an observer for
 546    * document activity notifications.
 547    */
 548   size_t mOutstandingDecodePromises;
 549
 550   /**
 551    * An incrementing counter representing the current request generation;
 552    * Each time mCurrentRequest is modified with a different URI, this will
 553    * be incremented. Each QueueDecodeAsync call will cache the generation
 554    * of the current request so that when it is processed, it knows if it
 555    * should have rejected because the request changed.
 556    */
 557   uint32_t mRequestGeneration;
 558
 559   bool mLoadingEnabled : 1;
 560
 561  protected:
 562   /**
 563    * The state we had the last time we checked whether we needed to notify the
 564    * document of a state change.  These are maintained by UpdateImageState.
 565    */
 566   bool mLoading : 1;
 567
 568   /**
 569    * A hack to get animations to reset, see bug 594771. On requests
 570    * that originate from setting .src, we mark them for needing their animation
 571    * reset when they are ready. mNewRequestsWillNeedAnimationReset is set to
 572    * true while preparing such requests (as a hack around needing to change an
 573    * interface), and the other two booleans store which of the current
 574    * and pending requests are of the sort that need their animation restarted.
 575    */
 576   bool mNewRequestsWillNeedAnimationReset : 1;
 577
 578   /**
 579    * Flag to indicate whether the channel should be mark as urgent-start.
 580    * It should be set in *Element and passed to nsContentUtils::LoadImage.
 581    * True if we want to set nsIClassOfService::UrgentStart to the channel to
 582    * get the response ASAP for better user responsiveness.
 583    */
 584   bool mUseUrgentStartForChannel : 1;
 585
 586   // Represents the image is deferred loading until this element gets visible.
 587   bool mLazyLoading : 1;
 588
 589  private:
 590   /* The number of nested AutoStateChangers currently tracking our state. */
 591   uint8_t mStateChangerDepth;
 592
 593   // Flags to indicate whether each of the current and pending requests are
 594   // registered with the refresh driver.
 595   bool mCurrentRequestRegistered;
 596   bool mPendingRequestRegistered;
 597
 598   // TODO:
 599   // Bug 1353685: Should ServiceWorker call SetBlockedRequest?
 600   //
 601   // This member is used in SetBlockedRequest, if it's true, then this call is
 602   // triggered from LoadImage.
 603   // If this is false, it means this call is from other places like
 604   // ServiceWorker, then we will ignore call to SetBlockedRequest for now.
 605   //
 606   // Also we use this variable to check if some evil code is reentering
 607   // LoadImage.
 608   bool mIsStartingImageLoad;
 609
 610   // If true, force frames to synchronously decode images on draw.
 611   bool mSyncDecodingHint;
 612 };
 613
 614 #endif  // nsImageLoadingContent_h__