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