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/. */
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).
13 #ifndef nsImageLoadingContent_h__
14 #define nsImageLoadingContent_h__
16 #include "imgINotificationObserver.h"
17 #include "mozilla/CORSMode.h"
18 #include "mozilla/EventStates.h"
19 #include "mozilla/TimeStamp.h"
21 #include "nsIContentPolicy.h"
22 #include "nsIImageLoadingContent.h"
23 #include "nsIRequest.h"
24 #include "mozilla/dom/BindingDeclarations.h"
25 #include "mozilla/dom/Promise.h"
26 #include "nsAttrValue.h"
33 class imgRequestProxy
;
36 class AsyncEventDispatcher
;
44 } // namespace mozilla
47 // Undefine LoadImage to prevent naming conflict with Windows.
51 class nsImageLoadingContent
: public nsIImageLoadingContent
{
54 using Maybe
= mozilla::Maybe
<T
>;
55 using Nothing
= mozilla::Nothing
;
56 using OnNonvisible
= mozilla::OnNonvisible
;
57 using Visibility
= mozilla::Visibility
;
61 nsImageLoadingContent();
62 virtual ~nsImageLoadingContent();
64 NS_DECL_IMGINOTIFICATIONOBSERVER
65 NS_DECL_NSIIMAGELOADINGCONTENT
67 // Web IDL binding methods.
68 // Note that the XPCOM SetLoadingEnabled, ForceImageState methods are OK for
69 // Web IDL bindings to use as well, since none of them throw when called via
70 // the Web IDL bindings.
72 bool LoadingEnabled() const { return mLoadingEnabled
; }
73 void AddObserver(imgINotificationObserver
* aObserver
);
74 void RemoveObserver(imgINotificationObserver
* aObserver
);
75 already_AddRefed
<imgIRequest
> GetRequest(int32_t aRequestType
,
76 mozilla::ErrorResult
& aError
);
77 int32_t GetRequestType(imgIRequest
* aRequest
, mozilla::ErrorResult
& aError
);
78 already_AddRefed
<nsIURI
> GetCurrentURI();
79 already_AddRefed
<nsIURI
> GetCurrentRequestFinalURI();
80 void ForceReload(bool aNotify
, mozilla::ErrorResult
& aError
);
82 mozilla::dom::Element
* FindImageMap();
85 * Toggle whether or not to synchronously decode an image on draw.
87 void SetSyncDecodingHint(bool aHint
);
90 * Notify us that the document state has changed. Called by nsDocument so that
91 * we may reject any promises which require the document to be active.
93 void NotifyOwnerDocumentActivityChanged();
96 * Enables/disables image state forcing. When |aForce| is true, we force
97 * nsImageLoadingContent::ImageState() to return |aState|. Call again with
98 * |aForce| as false to revert ImageState() to its original behaviour.
100 void ForceImageState(bool aForce
, mozilla::EventStates::InternalType aState
);
104 // Most normal image loads
105 eImageLoadType_Normal
,
106 // From a <img srcset> or <picture> context. Affects type given to content
108 eImageLoadType_Imageset
112 * LoadImage is called by subclasses when the appropriate
113 * attributes (eg 'src' for <img> tags) change. The string passed
114 * in is the new uri string; this consolidates the code for getting
115 * the charset, constructing URI objects, and any other incidentals
116 * into this superclass.
118 * @param aNewURI the URI spec to be loaded (may be a relative URI)
119 * @param aForce If true, make sure to load the URI. If false, only
120 * load if the URI is different from the currently loaded URI.
121 * @param aNotify If true, nsIDocumentObserver state change notifications
122 * will be sent as needed.
123 * @param aImageLoadType The ImageLoadType for this request
124 * @param aTriggeringPrincipal Optional parameter specifying the triggering
125 * principal to use for the image load
127 nsresult
LoadImage(const nsAString
& aNewURI
, bool aForce
, bool aNotify
,
128 ImageLoadType aImageLoadType
,
129 nsIPrincipal
* aTriggeringPrincipal
= nullptr);
132 * ImageState is called by subclasses that are computing their content state.
133 * The return value will have the NS_EVENT_STATE_BROKEN bit set as needed.
135 * Note that this state assumes that this node is "trying" to be an
136 * image (so for example complete lack of attempt to load an image will lead
137 * to NS_EVENT_STATE_BROKEN being set). Subclasses that are not "trying" to
138 * be an image (eg an HTML <input> of type other than "image") should just
139 * not call this method when computing their intrinsic state.
141 mozilla::EventStates
ImageState() const;
144 * LoadImage is called by subclasses when the appropriate
145 * attributes (eg 'src' for <img> tags) change. If callers have an
146 * URI object already available, they should use this method.
148 * @param aNewURI the URI to be loaded
149 * @param aForce If true, make sure to load the URI. If false, only
150 * load if the URI is different from the currently loaded URI.
151 * @param aNotify If true, nsIDocumentObserver state change notifications
152 * will be sent as needed.
153 * @param aImageLoadType The ImageLoadType for this request
154 * @param aDocument Optional parameter giving the document this node is in.
155 * This is purely a performance optimization.
156 * @param aLoadFlags Optional parameter specifying load flags to use for
158 * @param aTriggeringPrincipal Optional parameter specifying the triggering
159 * principal to use for the image load
161 nsresult
LoadImage(nsIURI
* aNewURI
, bool aForce
, bool aNotify
,
162 ImageLoadType aImageLoadType
, nsLoadFlags aLoadFlags
,
163 mozilla::dom::Document
* aDocument
= nullptr,
164 nsIPrincipal
* aTriggeringPrincipal
= nullptr);
166 nsresult
LoadImage(nsIURI
* aNewURI
, bool aForce
, bool aNotify
,
167 ImageLoadType aImageLoadType
,
168 nsIPrincipal
* aTriggeringPrincipal
) {
169 return LoadImage(aNewURI
, aForce
, aNotify
, aImageLoadType
, LoadFlags(),
170 nullptr, aTriggeringPrincipal
);
174 * helpers to get the document for this content (from the nodeinfo
175 * and such). Not named GetOwnerDoc/GetCurrentDoc to prevent ambiguous
176 * method names in subclasses
178 * @return the document we belong to
180 mozilla::dom::Document
* GetOurOwnerDoc();
181 mozilla::dom::Document
* GetOurCurrentDoc();
184 * Helper function to get the frame associated with this content. Not named
185 * GetPrimaryFrame to prevent ambiguous method names in subclasses.
187 * @return The frame which we belong to, or nullptr if it doesn't exist.
189 nsIFrame
* GetOurPrimaryFrame();
192 * Helper function to get the PresContext associated with this content's
193 * frame. Not named GetPresContext to prevent ambiguous method names in
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.
199 nsPresContext
* GetFramePresContext();
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).
206 void CancelImageRequests(bool aNotify
);
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.
218 * Returns the CORS mode that will be used for all future image loads. The
219 * default implementation returns CORS_NONE unconditionally.
221 virtual mozilla::CORSMode
GetCORSMode();
223 // Subclasses are *required* to call BindToTree/UnbindFromTree.
224 void BindToTree(mozilla::dom::BindContext
&, nsINode
& aParent
);
225 void UnbindFromTree(bool aNullParent
);
227 void OnLoadComplete(imgIRequest
* aRequest
, nsresult aStatus
);
228 void OnUnlockedDraw();
229 void OnImageIsAnimated(imgIRequest
* aRequest
);
231 // The nsContentPolicyType we would use for this ImageLoadType
232 static nsContentPolicyType
PolicyTypeForLoad(ImageLoadType aImageLoadType
);
234 void AsyncEventRunning(mozilla::AsyncEventDispatcher
* aEvent
);
236 // Get ourselves as an nsIContent*. Not const because some of the callers
237 // want a non-const nsIContent.
238 virtual nsIContent
* AsContent() = 0;
241 * Get width and height of the current request, using given image request if
242 * attributes are unset.
244 MOZ_CAN_RUN_SCRIPT
mozilla::CSSIntSize
GetWidthHeightForImage();
247 * Create a promise and queue a microtask which will ensure the current
248 * request (after any pending loads are applied) has requested a full decode.
249 * The promise is fulfilled once the request has a fully decoded surface that
250 * is available for drawing, or an error condition occurrs (e.g. broken image,
251 * current request is updated, etc).
253 * https://html.spec.whatwg.org/multipage/embedded-content.html#dom-img-decode
255 already_AddRefed
<mozilla::dom::Promise
> QueueDecodeAsync(
256 mozilla::ErrorResult
& aRv
);
258 enum class ImageDecodingType
: uint8_t {
264 static const nsAttrValue::EnumTable kDecodingTable
[];
265 static const nsAttrValue::EnumTable
* kDecodingTableDefault
;
269 * Enqueue and/or fulfill a promise created by QueueDecodeAsync.
271 void DecodeAsync(RefPtr
<mozilla::dom::Promise
>&& aPromise
,
272 uint32_t aRequestGeneration
);
275 * Attempt to resolve all queued promises based on the state of the current
276 * request. If the current request does not yet have all of the encoded data,
277 * or the decoding has not yet completed, it will return without changing the
280 void MaybeResolveDecodePromises();
283 * Reject all queued promises with the given status.
285 void RejectDecodePromises(nsresult aStatus
);
288 * Age the generation counter if we have a new current request with a
289 * different URI. If the generation counter is aged, then all queued promises
290 * will also be rejected.
292 void MaybeAgeRequestGeneration(nsIURI
* aNewURI
);
295 * Deregister as an observer for the owner document's activity notifications
296 * if we have no outstanding decode promises.
298 void MaybeDeregisterActivityObserver();
301 * Struct used to manage the native image observers.
303 struct ImageObserver
{
304 explicit ImageObserver(imgINotificationObserver
* aObserver
);
307 nsCOMPtr
<imgINotificationObserver
> mObserver
;
308 ImageObserver
* mNext
;
312 * Struct used to manage the scripted/XPCOM image observers.
314 class ScriptedImageObserver final
{
316 NS_INLINE_DECL_REFCOUNTING(ScriptedImageObserver
)
318 ScriptedImageObserver(imgINotificationObserver
* aObserver
,
319 RefPtr
<imgRequestProxy
>&& aCurrentRequest
,
320 RefPtr
<imgRequestProxy
>&& aPendingRequest
);
321 bool CancelRequests();
323 nsCOMPtr
<imgINotificationObserver
> mObserver
;
324 RefPtr
<imgRequestProxy
> mCurrentRequest
;
325 RefPtr
<imgRequestProxy
> mPendingRequest
;
328 ~ScriptedImageObserver();
332 * Struct to report state changes
334 struct AutoStateChanger
{
335 AutoStateChanger(nsImageLoadingContent
* aImageContent
, bool aNotify
)
336 : mImageContent(aImageContent
), mNotify(aNotify
) {
337 mImageContent
->mStateChangerDepth
++;
339 ~AutoStateChanger() {
340 mImageContent
->mStateChangerDepth
--;
341 mImageContent
->UpdateImageState(mNotify
);
344 nsImageLoadingContent
* mImageContent
;
348 friend struct AutoStateChanger
;
351 * Method to fire an event once we know what's going on with the image load.
353 * @param aEventType "loadstart", "loadend", "load", or "error" depending on
355 * @param aIsCancelable true if event is cancelable.
357 nsresult
FireEvent(const nsAString
& aEventType
, bool aIsCancelable
= false);
360 * Method to cancel and null-out pending event if they exist.
362 void CancelPendingEvent();
364 RefPtr
<mozilla::AsyncEventDispatcher
> mPendingEvent
;
368 * UpdateImageState recomputes the current state of this image loading
369 * content and updates what ImageState() returns accordingly. It will also
370 * fire a ContentStatesChanged() notification as needed if aNotify is true.
372 void UpdateImageState(bool aNotify
);
375 * Method to create an nsIURI object from the given string (will
376 * handle getting the right charset, base, etc). You MUST pass in a
377 * non-null document to this function.
379 * @param aSpec the string spec (from an HTML attribute, eg)
380 * @param aDocument the document we belong to
381 * @return the URI we want to be loading
383 nsresult
StringToURI(const nsAString
& aSpec
,
384 mozilla::dom::Document
* aDocument
, nsIURI
** aURI
);
387 * Prepare and returns a reference to the "next request". If there's already
388 * a _usable_ current request (one with SIZE_AVAILABLE), this request is
389 * "pending" until it becomes usable. Otherwise, this becomes the current
392 * @param aImageLoadType The ImageLoadType for this request
394 RefPtr
<imgRequestProxy
>& PrepareNextRequest(ImageLoadType aImageLoadType
);
397 * Returns a COMPtr reference to the current/pending image requests, cleaning
398 * up and canceling anything that was there before. Note that if you just want
399 * to get rid of one of the requests, you should call
400 * Clear*Request(NS_BINDING_ABORTED) instead.
402 * @param aImageLoadType The ImageLoadType for this request
404 RefPtr
<imgRequestProxy
>& PrepareCurrentRequest(ImageLoadType aImageLoadType
);
405 RefPtr
<imgRequestProxy
>& PreparePendingRequest(ImageLoadType aImageLoadType
);
408 * Switch our pending request to be our current request.
409 * mPendingRequest must be non-null!
411 void MakePendingRequestCurrent();
414 * Cancels and nulls-out the "current" and "pending" requests if they exist.
416 * @param aNonvisibleAction An action to take if the image is no longer
417 * visible as a result; see |UntrackImage|.
419 void ClearCurrentRequest(
421 const Maybe
<OnNonvisible
>& aNonvisibleAction
= Nothing());
422 void ClearPendingRequest(
424 const Maybe
<OnNonvisible
>& aNonvisibleAction
= Nothing());
427 * Retrieve a pointer to the 'registered with the refresh driver' flag for
428 * which a particular image request corresponds.
430 * @returns A pointer to the boolean flag for a given image request, or
431 * |nullptr| if the request is not either |mPendingRequest| or
434 bool* GetRegisteredFlagForRequest(imgIRequest
* aRequest
);
437 * Reset animation of the current request if
438 * |mNewRequestsWillNeedAnimationReset| was true when the request was
441 void ResetAnimationIfNeeded();
444 * Static helper method to tell us if we have the size of a request. The
447 static bool HaveSize(imgIRequest
* aImage
);
450 * Adds/Removes a given imgIRequest from our document's tracker.
452 * No-op if aImage is null.
454 * @param aFrame If called from FrameCreated the frame passed to FrameCreated.
455 * This is our frame, but at the time of the FrameCreated call
456 * our primary frame pointer hasn't been set yet, so this is
457 * only way to get our frame.
459 * @param aNonvisibleAction A requested action if the frame has become
460 * nonvisible. If Nothing(), no action is
461 * requested. If DISCARD_IMAGES is specified, the
462 * frame is requested to ask any images it's
463 * associated with to discard their surfaces if
466 void TrackImage(imgIRequest
* aImage
, nsIFrame
* aFrame
= nullptr);
467 void UntrackImage(imgIRequest
* aImage
,
468 const Maybe
<OnNonvisible
>& aNonvisibleAction
= Nothing());
470 nsLoadFlags
LoadFlags();
473 RefPtr
<imgRequestProxy
> mCurrentRequest
;
474 RefPtr
<imgRequestProxy
> mPendingRequest
;
475 uint32_t mCurrentRequestFlags
;
476 uint32_t mPendingRequestFlags
;
479 // Set if the request needs ResetAnimation called on it.
480 REQUEST_NEEDS_ANIMATION_RESET
= 0x00000001U
,
481 // Set if the request is currently tracked with the document.
482 REQUEST_IS_TRACKED
= 0x00000004U
,
483 // Set if this is an imageset request, such as from <img srcset> or
485 REQUEST_IS_IMAGESET
= 0x00000008U
488 // If the image was blocked or if there was an error loading, it's nice to
489 // still keep track of what the URI was despite not having an imgIRequest.
490 // We only maintain this in those situations (in the common case, this is
492 nsCOMPtr
<nsIURI
> mCurrentURI
;
496 * Clones the given "current" or "pending" request for each scripted observer.
498 void CloneScriptedRequests(imgRequestProxy
* aRequest
);
501 * Cancels and nulls-out the "current" or "pending" requests if they exist
502 * for each scripted observer.
504 void ClearScriptedRequests(int32_t aRequestType
, nsresult aReason
);
507 * Moves the "pending" request into the "current" request for each scripted
508 * observer. If there is an existing "current" request, it will cancel it
511 void MakePendingScriptedRequestsCurrent();
514 * Depending on the configured decoding hint, and/or how recently we updated
515 * the image request, force or stop the frame from decoding the image
516 * synchronously when it is drawn.
517 * @param aPrepareNextRequest True if this is when updating the image request.
518 * @param aFrame If called from FrameCreated the frame passed to FrameCreated.
519 * This is our frame, but at the time of the FrameCreated call
520 * our primary frame pointer hasn't been set yet, so this is
521 * only way to get our frame.
523 void MaybeForceSyncDecoding(bool aPrepareNextRequest
,
524 nsIFrame
* aFrame
= nullptr);
527 * Typically we will have only one observer (our frame in the screen
528 * prescontext), so we want to only make space for one and to
529 * heap-allocate anything past that (saves memory and malloc churn
530 * in the common case). The storage is a linked list, we just
531 * happen to actually hold the first observer instead of a pointer
534 ImageObserver mObserverList
;
537 * Typically we will have no scripted observers, as this is only used by
538 * chrome, legacy extensions, and some mochitests. An empty array reserves
541 nsTArray
<RefPtr
<ScriptedImageObserver
>> mScriptedObservers
;
544 * Promises created by QueueDecodeAsync that are still waiting to be
545 * fulfilled by the image being fully decoded.
547 nsTArray
<RefPtr
<mozilla::dom::Promise
>> mDecodePromises
;
550 * When mIsImageStateForced is true, this holds the ImageState that we'll
551 * return in ImageState().
553 mozilla::EventStates mForcedImageState
;
555 mozilla::TimeStamp mMostRecentRequestChange
;
558 * Total number of outstanding decode promises, including those stored in
559 * mDecodePromises and those embedded in runnables waiting to be enqueued.
560 * This is used to determine whether we need to register as an observer for
561 * document activity notifications.
563 size_t mOutstandingDecodePromises
;
566 * An incrementing counter representing the current request generation;
567 * Each time mCurrentRequest is modified with a different URI, this will
568 * be incremented. Each QueueDecodeAsync call will cache the generation
569 * of the current request so that when it is processed, it knows if it
570 * should have rejected because the request changed.
572 uint32_t mRequestGeneration
;
574 bool mLoadingEnabled
: 1;
577 * When true, we return mForcedImageState from ImageState().
579 bool mIsImageStateForced
: 1;
582 * The state we had the last time we checked whether we needed to notify the
583 * document of a state change. These are maintained by UpdateImageState.
590 * A hack to get animations to reset, see bug 594771. On requests
591 * that originate from setting .src, we mark them for needing their animation
592 * reset when they are ready. mNewRequestsWillNeedAnimationReset is set to
593 * true while preparing such requests (as a hack around needing to change an
594 * interface), and the other two booleans store which of the current
595 * and pending requests are of the sort that need their animation restarted.
597 bool mNewRequestsWillNeedAnimationReset
: 1;
600 * Flag to indicate whether the channel should be mark as urgent-start.
601 * It should be set in *Element and passed to nsContentUtils::LoadImage.
602 * True if we want to set nsIClassOfService::UrgentStart to the channel to
603 * get the response ASAP for better user responsiveness.
605 bool mUseUrgentStartForChannel
: 1;
607 // Represents the image is deferred loading until this element gets visible.
608 bool mLazyLoading
: 1;
611 /* The number of nested AutoStateChangers currently tracking our state. */
612 uint8_t mStateChangerDepth
;
614 // Flags to indicate whether each of the current and pending requests are
615 // registered with the refresh driver.
616 bool mCurrentRequestRegistered
;
617 bool mPendingRequestRegistered
;
620 // Bug 1353685: Should ServiceWorker call SetBlockedRequest?
622 // This member is used in SetBlockedRequest, if it's true, then this call is
623 // triggered from LoadImage.
624 // If this is false, it means this call is from other places like
625 // ServiceWorker, then we will ignore call to SetBlockedRequest for now.
627 // Also we use this variable to check if some evil code is reentering
629 bool mIsStartingImageLoad
;
631 // If true, force frames to synchronously decode images on draw.
632 bool mSyncDecodingHint
;
635 #endif // nsImageLoadingContent_h__