1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/image/public/imgIRequest.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,201 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
1.5 + *
1.6 + * This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +#include "nsISupports.idl"
1.11 +#include "nsIRequest.idl"
1.12 +
1.13 +interface imgIContainer;
1.14 +interface imgINotificationObserver;
1.15 +interface nsIURI;
1.16 +interface nsIPrincipal;
1.17 +
1.18 +/**
1.19 + * imgIRequest interface
1.20 + *
1.21 + * @author Stuart Parmenter <stuart@mozilla.com>
1.22 + * @version 0.1
1.23 + * @see imagelib2
1.24 + */
1.25 +[scriptable, builtinclass, uuid(9c709b50-bd1a-476d-b313-d64db874f80a)]
1.26 +interface imgIRequest : nsIRequest
1.27 +{
1.28 + /**
1.29 + * the image container...
1.30 + * @return the image object associated with the request.
1.31 + * @attention NEED DOCS
1.32 + */
1.33 + readonly attribute imgIContainer image;
1.34 +
1.35 + /**
1.36 + * Bits set in the return value from imageStatus
1.37 + * @name statusflags
1.38 + *
1.39 + * Meanings:
1.40 + *
1.41 + * STATUS_NONE: Nothing to report.
1.42 + *
1.43 + * STATUS_SIZE_AVAILABLE: We received enough image data
1.44 + * from the network or filesystem that we know the width
1.45 + * and height of the image, and have thus called SetSize()
1.46 + * on the container.
1.47 + *
1.48 + * STATUS_LOAD_PARTIAL: Used internally by imgRequest to
1.49 + * flag that a request is being cancelled as a result of
1.50 + * a failure of a proxy holder and not an internal failure.
1.51 + * At least I think that's what it does. Regardless, there's
1.52 + * no reason for this flag to be public, and it should either
1.53 + * go away or become a private state flag within imgRequest.
1.54 + * Don't rely on it.
1.55 + *
1.56 + * STATUS_LOAD_COMPLETE: The data has been fully loaded
1.57 + * to memory, but not necessarily fully decoded.
1.58 + *
1.59 + * STATUS_ERROR: An error occurred loading the image.
1.60 + *
1.61 + * STATUS_DECODE_STARTED: The decoding process has begun, but not yet
1.62 + * finished.
1.63 + *
1.64 + * STATUS_FRAME_COMPLETE: The first frame has been
1.65 + * completely decoded.
1.66 + *
1.67 + * STATUS_DECODE_COMPLETE: The whole image has been decoded.
1.68 + */
1.69 + //@{
1.70 + const long STATUS_NONE = 0x0;
1.71 + const long STATUS_SIZE_AVAILABLE = 0x1;
1.72 + const long STATUS_LOAD_PARTIAL = 0x2;
1.73 + const long STATUS_LOAD_COMPLETE = 0x4;
1.74 + const long STATUS_ERROR = 0x8;
1.75 + const long STATUS_DECODE_STARTED = 0x10;
1.76 + const long STATUS_FRAME_COMPLETE = 0x20;
1.77 + const long STATUS_DECODE_COMPLETE = 0x40;
1.78 + //@}
1.79 +
1.80 + /**
1.81 + * Status flags of the STATUS_* variety.
1.82 + */
1.83 + readonly attribute unsigned long imageStatus;
1.84 +
1.85 + /**
1.86 + * The URI the image load was started with. Note that this might not be the
1.87 + * actual URI for the image (e.g. if HTTP redirects happened during the
1.88 + * load).
1.89 + */
1.90 + readonly attribute nsIURI URI;
1.91 +
1.92 + readonly attribute imgINotificationObserver notificationObserver;
1.93 +
1.94 + readonly attribute string mimeType;
1.95 +
1.96 + /**
1.97 + * Clone this request; the returned request will have aObserver as the
1.98 + * observer. aObserver will be notified synchronously (before the clone()
1.99 + * call returns) with all the notifications that have already been dispatched
1.100 + * for this image load.
1.101 + */
1.102 + imgIRequest clone(in imgINotificationObserver aObserver);
1.103 +
1.104 + /**
1.105 + * The principal gotten from the channel the image was loaded from.
1.106 + */
1.107 + readonly attribute nsIPrincipal imagePrincipal;
1.108 +
1.109 + /**
1.110 + * Whether the request is multipart (ie, multipart/x-mixed-replace)
1.111 + */
1.112 + readonly attribute bool multipart;
1.113 +
1.114 + /**
1.115 + * CORS modes images can be loaded with.
1.116 + *
1.117 + * By default, all images are loaded with CORS_NONE and cannot be used
1.118 + * cross-origin in context like WebGL.
1.119 + *
1.120 + * If an HTML img element has the crossorigin attribute set, the imgIRequest
1.121 + * will be validated for cross-origin usage with CORS, and, if successful,
1.122 + * will have its CORS mode set to the relevant type.
1.123 + */
1.124 + //@{
1.125 + const long CORS_NONE = 1;
1.126 + const long CORS_ANONYMOUS = 2;
1.127 + const long CORS_USE_CREDENTIALS = 3;
1.128 + //@}
1.129 +
1.130 + /**
1.131 + * The CORS mode that this image was loaded with.
1.132 + */
1.133 + readonly attribute long CORSMode;
1.134 +
1.135 + /**
1.136 + * Cancels this request as in nsIRequest::Cancel(); further, also nulls out
1.137 + * decoderObserver so it gets no further notifications from us.
1.138 + *
1.139 + * NOTE: You should not use this in any new code; instead, use cancel(). Note
1.140 + * that cancel() is asynchronous, which means that some time after you call
1.141 + * it, the listener/observer will get an OnStopRequest(). This means that, if
1.142 + * you're the observer, you can't call cancel() from your destructor.
1.143 + */
1.144 + void cancelAndForgetObserver(in nsresult aStatus);
1.145 +
1.146 + /**
1.147 + * Requests a decode for the image.
1.148 + *
1.149 + * imgIContainer has a requestDecode() method, but callers may want to request
1.150 + * a decode before the container has necessarily been instantiated. Calling
1.151 + * requestDecode() on the imgIRequest simply forwards along the request if the
1.152 + * container already exists, or calls it once it gets OnStartContainer if the
1.153 + * container does not yet exist.
1.154 + */
1.155 + void requestDecode();
1.156 + void startDecoding();
1.157 +
1.158 + /**
1.159 + * Locks an image. If the image does not exist yet, locks it once it becomes
1.160 + * available. The lock persists for the lifetime of the imgIRequest (until
1.161 + * unlockImage is called) even if the underlying image changes.
1.162 + *
1.163 + * If you don't call unlockImage() by the time this imgIRequest goes away, it
1.164 + * will be called for you automatically.
1.165 + *
1.166 + * @see imgIContainer::lockImage for documentation of the underlying call.
1.167 + */
1.168 + void lockImage();
1.169 +
1.170 + /**
1.171 + * Unlocks an image.
1.172 + *
1.173 + * @see imgIContainer::unlockImage for documentation of the underlying call.
1.174 + */
1.175 + void unlockImage();
1.176 +
1.177 + /**
1.178 + * If this image is unlocked, discard the image's decoded data. If the image
1.179 + * is locked or is already discarded, do nothing.
1.180 + */
1.181 + void requestDiscard();
1.182 +
1.183 + /**
1.184 + * If this request is for an animated image, the method creates a new
1.185 + * request which contains the current frame of the image.
1.186 + * Otherwise returns the same request.
1.187 + */
1.188 + imgIRequest getStaticRequest();
1.189 +
1.190 + /**
1.191 + * Requests that the image animate (if it has an animation).
1.192 + *
1.193 + * @see Image::IncrementAnimationConsumers for documentation of the underlying call.
1.194 + */
1.195 + void incrementAnimationConsumers();
1.196 +
1.197 + /**
1.198 + * Tell the image it can forget about a request that the image animate.
1.199 + *
1.200 + * @see Image::DecrementAnimationConsumers for documentation of the underlying call.
1.201 + */
1.202 + void decrementAnimationConsumers();
1.203 +};
1.204 +
