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: 
michael@0: interface nsIInputStream;
michael@0: interface imgIContainer;
michael@0: interface imgILoader;
michael@0: interface imgICache;
michael@0: interface nsIDOMDocument;
michael@0: interface imgIScriptedNotificationObserver;
michael@0: interface imgINotificationObserver;
michael@0: 
michael@0: [scriptable, builtinclass, uuid(4c2383a4-931c-484d-8c4a-973590f66e3f)]
michael@0: interface imgITools : nsISupports
michael@0: {
michael@0:     /**
michael@0:      * decodeImage
michael@0:      * Caller provides an input stream and mimetype. We read from the stream
michael@0:      * and decompress it (according to the specified mime type) and return
michael@0:      * the resulting imgIContainer.
michael@0:      *
michael@0:      * @param aStream
michael@0:      *        An input stream for an encoded image file.
michael@0:      * @param aMimeType
michael@0:      *        Type of image in the stream.
michael@0:      */
michael@0:     imgIContainer decodeImage(in nsIInputStream aStream,
michael@0:                               in ACString aMimeType);
michael@0: 
michael@0:     /**
michael@0:      * decodeImageData
michael@0:      * Caller provides an input stream and mimetype. We read from the stream
michael@0:      * and decompress it (according to the specified mime type) and return
michael@0:      * the resulting imgIContainer.
michael@0:      *
michael@0:      * This method is deprecated and will be removed at some time in the future;
michael@0:      * new code should use |decodeImage|.
michael@0:      *
michael@0:      * @param aStream
michael@0:      *        An input stream for an encoded image file.
michael@0:      * @param aMimeType
michael@0:      *        Type of image in the stream.
michael@0:      * @param aContainer
michael@0:      *        An imgIContainer holding the decoded image will be returned via
michael@0:      *        this parameter. It is an error to provide any initial value but
michael@0:      *        |null|.
michael@0:      */
michael@0:     [deprecated] void decodeImageData(in nsIInputStream aStream,
michael@0:                                       in ACString aMimeType,
michael@0:                                       inout imgIContainer aContainer);
michael@0: 
michael@0:     /**
michael@0:      * encodeImage
michael@0:      * Caller provides an image container, and the mime type it should be
michael@0:      * encoded to. We return an input stream for the encoded image data.
michael@0:      *
michael@0:      * @param aContainer
michael@0:      *        An image container.
michael@0:      * @param aMimeType
michael@0:      *        Type of encoded image desired (eg "image/png").
michael@0:      * @param outputOptions
michael@0:      *        Encoder-specific output options.
michael@0:      */
michael@0:     nsIInputStream encodeImage(in imgIContainer aContainer,
michael@0:                                in ACString aMimeType,
michael@0:                                [optional] in AString outputOptions);
michael@0: 
michael@0:     /**
michael@0:      * encodeScaledImage
michael@0:      * Caller provides an image container, and the mime type it should be
michael@0:      * encoded to. We return an input stream for the encoded image data.
michael@0:      * The encoded image is scaled to the specified dimensions.
michael@0:      *
michael@0:      * @param aContainer
michael@0:      *        An image container.
michael@0:      * @param aMimeType
michael@0:      *        Type of encoded image desired (eg "image/png").
michael@0:      * @param aWidth, aHeight
michael@0:      *        The size (in pixels) desired for the resulting image. Specify 0 to
michael@0:      *        use the given image's width or height. Values must be >= 0.
michael@0:      * @param outputOptions
michael@0:      *        Encoder-specific output options.
michael@0:      */
michael@0:     nsIInputStream encodeScaledImage(in imgIContainer aContainer,
michael@0:                                      in ACString aMimeType,
michael@0:                                      in long aWidth,
michael@0:                                      in long aHeight,
michael@0:                                      [optional] in AString outputOptions);
michael@0: 
michael@0:     /**
michael@0:      * getImgLoaderForDocument
michael@0:      * Retrieve an image loader that reflects the privacy status of the given
michael@0:      * document.
michael@0:      *
michael@0:      * @param doc
michael@0:      *        A document. Must not be null.
michael@0:      */
michael@0:     imgILoader getImgLoaderForDocument(in nsIDOMDocument doc);
michael@0: 
michael@0:     /**
michael@0:      * getImgLoaderForDocument
michael@0:      * Retrieve an image cache that reflects the privacy status of the given
michael@0:      * document.
michael@0:      *
michael@0:      * @param doc
michael@0:      *        A document. Null is allowed, but must _only_ be passed
michael@0:      *        when there is no way to obtain a relevant document for
michael@0:      *        the current context in which a cache is desired.
michael@0:      */
michael@0:     imgICache getImgCacheForDocument(in nsIDOMDocument doc);
michael@0: 
michael@0:     /**
michael@0:      * encodeCroppedImage
michael@0:      * Caller provides an image container, and the mime type it should be
michael@0:      * encoded to. We return an input stream for the encoded image data.
michael@0:      * The encoded image is cropped to the specified dimensions.
michael@0:      *
michael@0:      * The given offset and size must not exceed the image bounds.
michael@0:      *
michael@0:      * @param aContainer
michael@0:      *        An image container.
michael@0:      * @param aMimeType
michael@0:      *        Type of encoded image desired (eg "image/png").
michael@0:      * @param aOffsetX, aOffsetY
michael@0:      *        The crop offset (in pixels). Values must be >= 0.
michael@0:      * @param aWidth, aHeight
michael@0:      *        The size (in pixels) desired for the resulting image. Specify 0 to
michael@0:      *        use the given image's width or height. Values must be >= 0.
michael@0:      * @param outputOptions
michael@0:      *        Encoder-specific output options.
michael@0:      */
michael@0:     nsIInputStream encodeCroppedImage(in imgIContainer aContainer,
michael@0:                                       in ACString aMimeType,
michael@0:                                       in long aOffsetX,
michael@0:                                       in long aOffsetY,
michael@0:                                       in long aWidth,
michael@0:                                       in long aHeight,
michael@0:                                       [optional] in AString outputOptions);
michael@0: 
michael@0:     /**
michael@0:      * Create a wrapper around a scripted notification observer (ordinarily
michael@0:      * imgINotificationObserver cannot be implemented from scripts).
michael@0:      *
michael@0:      * @param aObserver The scripted observer to wrap 
michael@0:      */
michael@0:     imgINotificationObserver createScriptedObserver(in imgIScriptedNotificationObserver aObserver);
michael@0: };