michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- michael@0: * michael@0: * This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: #include "nsISupports.idl" michael@0: #include "nsIRequest.idl" michael@0: michael@0: interface imgIContainer; michael@0: interface imgINotificationObserver; michael@0: interface nsIURI; michael@0: interface nsIPrincipal; michael@0: michael@0: /** michael@0: * imgIRequest interface michael@0: * michael@0: * @author Stuart Parmenter michael@0: * @version 0.1 michael@0: * @see imagelib2 michael@0: */ michael@0: [scriptable, builtinclass, uuid(9c709b50-bd1a-476d-b313-d64db874f80a)] michael@0: interface imgIRequest : nsIRequest michael@0: { michael@0: /** michael@0: * the image container... michael@0: * @return the image object associated with the request. michael@0: * @attention NEED DOCS michael@0: */ michael@0: readonly attribute imgIContainer image; michael@0: michael@0: /** michael@0: * Bits set in the return value from imageStatus michael@0: * @name statusflags michael@0: * michael@0: * Meanings: michael@0: * michael@0: * STATUS_NONE: Nothing to report. michael@0: * michael@0: * STATUS_SIZE_AVAILABLE: We received enough image data michael@0: * from the network or filesystem that we know the width michael@0: * and height of the image, and have thus called SetSize() michael@0: * on the container. michael@0: * michael@0: * STATUS_LOAD_PARTIAL: Used internally by imgRequest to michael@0: * flag that a request is being cancelled as a result of michael@0: * a failure of a proxy holder and not an internal failure. michael@0: * At least I think that's what it does. Regardless, there's michael@0: * no reason for this flag to be public, and it should either michael@0: * go away or become a private state flag within imgRequest. michael@0: * Don't rely on it. michael@0: * michael@0: * STATUS_LOAD_COMPLETE: The data has been fully loaded michael@0: * to memory, but not necessarily fully decoded. michael@0: * michael@0: * STATUS_ERROR: An error occurred loading the image. michael@0: * michael@0: * STATUS_DECODE_STARTED: The decoding process has begun, but not yet michael@0: * finished. michael@0: * michael@0: * STATUS_FRAME_COMPLETE: The first frame has been michael@0: * completely decoded. michael@0: * michael@0: * STATUS_DECODE_COMPLETE: The whole image has been decoded. michael@0: */ michael@0: //@{ michael@0: const long STATUS_NONE = 0x0; michael@0: const long STATUS_SIZE_AVAILABLE = 0x1; michael@0: const long STATUS_LOAD_PARTIAL = 0x2; michael@0: const long STATUS_LOAD_COMPLETE = 0x4; michael@0: const long STATUS_ERROR = 0x8; michael@0: const long STATUS_DECODE_STARTED = 0x10; michael@0: const long STATUS_FRAME_COMPLETE = 0x20; michael@0: const long STATUS_DECODE_COMPLETE = 0x40; michael@0: //@} michael@0: michael@0: /** michael@0: * Status flags of the STATUS_* variety. michael@0: */ michael@0: readonly attribute unsigned long imageStatus; michael@0: michael@0: /** michael@0: * The URI the image load was started with. Note that this might not be the michael@0: * actual URI for the image (e.g. if HTTP redirects happened during the michael@0: * load). michael@0: */ michael@0: readonly attribute nsIURI URI; michael@0: michael@0: readonly attribute imgINotificationObserver notificationObserver; michael@0: michael@0: readonly attribute string mimeType; michael@0: michael@0: /** michael@0: * Clone this request; the returned request will have aObserver as the michael@0: * observer. aObserver will be notified synchronously (before the clone() michael@0: * call returns) with all the notifications that have already been dispatched michael@0: * for this image load. michael@0: */ michael@0: imgIRequest clone(in imgINotificationObserver aObserver); michael@0: michael@0: /** michael@0: * The principal gotten from the channel the image was loaded from. michael@0: */ michael@0: readonly attribute nsIPrincipal imagePrincipal; michael@0: michael@0: /** michael@0: * Whether the request is multipart (ie, multipart/x-mixed-replace) michael@0: */ michael@0: readonly attribute bool multipart; michael@0: michael@0: /** michael@0: * CORS modes images can be loaded with. michael@0: * michael@0: * By default, all images are loaded with CORS_NONE and cannot be used michael@0: * cross-origin in context like WebGL. michael@0: * michael@0: * If an HTML img element has the crossorigin attribute set, the imgIRequest michael@0: * will be validated for cross-origin usage with CORS, and, if successful, michael@0: * will have its CORS mode set to the relevant type. michael@0: */ michael@0: //@{ michael@0: const long CORS_NONE = 1; michael@0: const long CORS_ANONYMOUS = 2; michael@0: const long CORS_USE_CREDENTIALS = 3; michael@0: //@} michael@0: michael@0: /** michael@0: * The CORS mode that this image was loaded with. michael@0: */ michael@0: readonly attribute long CORSMode; michael@0: michael@0: /** michael@0: * Cancels this request as in nsIRequest::Cancel(); further, also nulls out michael@0: * decoderObserver so it gets no further notifications from us. michael@0: * michael@0: * NOTE: You should not use this in any new code; instead, use cancel(). Note michael@0: * that cancel() is asynchronous, which means that some time after you call michael@0: * it, the listener/observer will get an OnStopRequest(). This means that, if michael@0: * you're the observer, you can't call cancel() from your destructor. michael@0: */ michael@0: void cancelAndForgetObserver(in nsresult aStatus); michael@0: michael@0: /** michael@0: * Requests a decode for the image. michael@0: * michael@0: * imgIContainer has a requestDecode() method, but callers may want to request michael@0: * a decode before the container has necessarily been instantiated. Calling michael@0: * requestDecode() on the imgIRequest simply forwards along the request if the michael@0: * container already exists, or calls it once it gets OnStartContainer if the michael@0: * container does not yet exist. michael@0: */ michael@0: void requestDecode(); michael@0: void startDecoding(); michael@0: michael@0: /** michael@0: * Locks an image. If the image does not exist yet, locks it once it becomes michael@0: * available. The lock persists for the lifetime of the imgIRequest (until michael@0: * unlockImage is called) even if the underlying image changes. michael@0: * michael@0: * If you don't call unlockImage() by the time this imgIRequest goes away, it michael@0: * will be called for you automatically. michael@0: * michael@0: * @see imgIContainer::lockImage for documentation of the underlying call. michael@0: */ michael@0: void lockImage(); michael@0: michael@0: /** michael@0: * Unlocks an image. michael@0: * michael@0: * @see imgIContainer::unlockImage for documentation of the underlying call. michael@0: */ michael@0: void unlockImage(); michael@0: michael@0: /** michael@0: * If this image is unlocked, discard the image's decoded data. If the image michael@0: * is locked or is already discarded, do nothing. michael@0: */ michael@0: void requestDiscard(); michael@0: michael@0: /** michael@0: * If this request is for an animated image, the method creates a new michael@0: * request which contains the current frame of the image. michael@0: * Otherwise returns the same request. michael@0: */ michael@0: imgIRequest getStaticRequest(); michael@0: michael@0: /** michael@0: * Requests that the image animate (if it has an animation). michael@0: * michael@0: * @see Image::IncrementAnimationConsumers for documentation of the underlying call. michael@0: */ michael@0: void incrementAnimationConsumers(); michael@0: michael@0: /** michael@0: * Tell the image it can forget about a request that the image animate. michael@0: * michael@0: * @see Image::DecrementAnimationConsumers for documentation of the underlying call. michael@0: */ michael@0: void decrementAnimationConsumers(); michael@0: }; michael@0: