image/imgITools.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   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 #include "nsISupports.idl"
   8
   9 interface nsIChannel;
  10 interface nsIEventTarget;
  11 interface nsIInputStream;
  12 interface nsIURI;
  13 interface imgIContainer;
  14 interface imgILoader;
  15 interface imgICache;
  16 interface imgIScriptedNotificationObserver;
  17 interface imgINotificationObserver;
  18 interface imgIContainerCallback;
  19
  20 webidl Document;
  21
  22 [scriptable, builtinclass, uuid(4c2383a4-931c-484d-8c4a-973590f66e3f)]
  23 interface imgITools : nsISupports
  24 {
  25     /**
  26      * decodeImageFromBuffer
  27      * Caller provides an buffer, a buffer size and a mimetype. We read from
  28      * the stream and decompress it (according to the specified mime type) and
  29      * return the resulting imgIContainer.
  30      *
  31      * @param aBuffer
  32      *        Data in memory.
  33      * @param aSize
  34      *        Buffer size.
  35      * @param aMimeType
  36      *        Type of image in the stream.
  37      */
  38     imgIContainer decodeImageFromBuffer(in string aBuffer,
  39                                         in unsigned long aSize,
  40                                         in ACString aMimeType);
  41
  42     /**
  43      * decodeImageFromArrayBuffer
  44      * Caller provides an ArrayBuffer and a mimetype. We read from
  45      * the stream and decompress it (according to the specified mime type) and
  46      * return the resulting imgIContainer.
  47      *
  48      * @param aArrayBuffer
  49      *        An ArrayBuffer.
  50      * @param aMimeType
  51      *        Type of image in the stream.
  52      */
  53     [implicit_jscontext]
  54     imgIContainer decodeImageFromArrayBuffer(in jsval aArrayBuffer,
  55                                              in ACString aMimeType);
  56
  57     /**
  58      * decodeImageFromChannelAsync
  59      * See decodeImage. The main difference between this method and decodeImage
  60      * is that here the operation is done async on a thread from the decode
  61      * pool. When the operation is completed, the callback is executed with the
  62      * result.
  63      *
  64      * @param aURI
  65      *        The original URI of the image
  66      * @param aChannel
  67      *        Channel to the image to be decoded.
  68      * @param aCallback
  69      *        The callback is executed when the imgContainer is fully created.
  70      * @param aObserver
  71      *        Optional observer for the decoded image, the caller should make
  72      *        sure the observer is kept alive as long as necessary, as ImageLib
  73      *        does not keep a strong reference to the observer.
  74      */
  75     void decodeImageFromChannelAsync(in nsIURI aURI,
  76                                      in nsIChannel aChannel,
  77                                      in imgIContainerCallback aCallback,
  78                                      in imgINotificationObserver aObserver);
  79
  80     /**
  81      * decodeImageAsync
  82      * See decodeImage. The main difference between this method and decodeImage
  83      * is that here the operation is done async on a thread from the decode
  84      * pool. When the operation is completed, the callback is executed with the
  85      * result.
  86      *
  87      * @param aStream
  88      *        An input stream for an encoded image file.
  89      * @param aMimeType
  90      *        Type of image in the stream.
  91      * @param aCallback
  92      *        The callback is executed when the imgContainer is fully created.
  93      * @param aEventTarget
  94      *        This eventTarget is used to execute aCallback
  95      */
  96     void decodeImageAsync(in nsIInputStream aStream,
  97                           in ACString aMimeType,
  98                           in imgIContainerCallback aCallback,
  99                           in nsIEventTarget aEventTarget);
 100
 101     /**
 102      * encodeImage
 103      * Caller provides an image container, and the mime type it should be
 104      * encoded to. We return an input stream for the encoded image data.
 105      *
 106      * @param aContainer
 107      *        An image container.
 108      * @param aMimeType
 109      *        Type of encoded image desired (eg "image/png").
 110      * @param outputOptions
 111      *        Encoder-specific output options.
 112      */
 113     nsIInputStream encodeImage(in imgIContainer aContainer,
 114                                in ACString aMimeType,
 115                                [optional] in AString outputOptions);
 116
 117     /**
 118      * encodeScaledImage
 119      * Caller provides an image container, and the mime type it should be
 120      * encoded to. We return an input stream for the encoded image data.
 121      * The encoded image is scaled to the specified dimensions.
 122      *
 123      * @param aContainer
 124      *        An image container.
 125      * @param aMimeType
 126      *        Type of encoded image desired (eg "image/png").
 127      * @param aWidth, aHeight
 128      *        The size (in pixels) desired for the resulting image. Specify 0 to
 129      *        use the given image's width or height. Values must be >= 0.
 130      * @param outputOptions
 131      *        Encoder-specific output options.
 132      */
 133     nsIInputStream encodeScaledImage(in imgIContainer aContainer,
 134                                      in ACString aMimeType,
 135                                      in long aWidth,
 136                                      in long aHeight,
 137                                      [optional] in AString outputOptions);
 138
 139     /**
 140      * getImgLoaderForDocument
 141      * Retrieve an image loader that reflects the privacy status of the given
 142      * document.
 143      *
 144      * @param doc
 145      *        A document. Must not be null.
 146      */
 147     imgILoader getImgLoaderForDocument(in Document doc);
 148
 149     /**
 150      * getImgLoaderForDocument
 151      * Retrieve an image cache that reflects the privacy status of the given
 152      * document.
 153      *
 154      * @param doc
 155      *        A document. Null is allowed, but must _only_ be passed
 156      *        when there is no way to obtain a relevant document for
 157      *        the current context in which a cache is desired.
 158      */
 159     imgICache getImgCacheForDocument(in Document doc);
 160
 161     /**
 162      * encodeCroppedImage
 163      * Caller provides an image container, and the mime type it should be
 164      * encoded to. We return an input stream for the encoded image data.
 165      * The encoded image is cropped to the specified dimensions.
 166      *
 167      * The given offset and size must not exceed the image bounds.
 168      *
 169      * @param aContainer
 170      *        An image container.
 171      * @param aMimeType
 172      *        Type of encoded image desired (eg "image/png").
 173      * @param aOffsetX, aOffsetY
 174      *        The crop offset (in pixels). Values must be >= 0.
 175      * @param aWidth, aHeight
 176      *        The size (in pixels) desired for the resulting image. Specify 0 to
 177      *        use the given image's width or height. Values must be >= 0.
 178      * @param outputOptions
 179      *        Encoder-specific output options.
 180      */
 181     nsIInputStream encodeCroppedImage(in imgIContainer aContainer,
 182                                       in ACString aMimeType,
 183                                       in long aOffsetX,
 184                                       in long aOffsetY,
 185                                       in long aWidth,
 186                                       in long aHeight,
 187                                       [optional] in AString outputOptions);
 188
 189     /**
 190      * Create a wrapper around a scripted notification observer (ordinarily
 191      * imgINotificationObserver cannot be implemented from scripts).
 192      *
 193      * @param aObserver The scripted observer to wrap
 194      */
 195     imgINotificationObserver
 196     createScriptedObserver(in imgIScriptedNotificationObserver aObserver);
 197 };
 198
 199 /**
 200  * This is a companion interface for nsIAsyncInputStream::asyncWait.
 201  */
 202 [function, scriptable, uuid(f195772c-a4c0-47ae-80ca-211e001c67be)]
 203 interface imgIContainerCallback : nsISupports
 204 {
 205     /* If the operation fails, aStatus will contain the error value */
 206     void onImageReady(in imgIContainer aImage, in nsresult aStatus);
 207 };