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 nsIInputStream;
  10 interface imgIContainer;
  11 interface imgILoader;
  12 interface imgICache;
  13 interface nsIDOMDocument;
  14 interface imgIScriptedNotificationObserver;
  15 interface imgINotificationObserver;
  16
  17 [scriptable, builtinclass, uuid(4c2383a4-931c-484d-8c4a-973590f66e3f)]
  18 interface imgITools : nsISupports
  19 {
  20     /**
  21      * decodeImage
  22      * Caller provides an input stream and mimetype. We read from the stream
  23      * and decompress it (according to the specified mime type) and return
  24      * the resulting imgIContainer.
  25      *
  26      * @param aStream
  27      *        An input stream for an encoded image file.
  28      * @param aMimeType
  29      *        Type of image in the stream.
  30      */
  31     imgIContainer decodeImage(in nsIInputStream aStream,
  32                               in ACString aMimeType);
  33
  34     /**
  35      * decodeImageData
  36      * Caller provides an input stream and mimetype. We read from the stream
  37      * and decompress it (according to the specified mime type) and return
  38      * the resulting imgIContainer.
  39      *
  40      * This method is deprecated and will be removed at some time in the future;
  41      * new code should use |decodeImage|.
  42      *
  43      * @param aStream
  44      *        An input stream for an encoded image file.
  45      * @param aMimeType
  46      *        Type of image in the stream.
  47      * @param aContainer
  48      *        An imgIContainer holding the decoded image will be returned via
  49      *        this parameter. It is an error to provide any initial value but
  50      *        |null|.
  51      */
  52     [deprecated] void decodeImageData(in nsIInputStream aStream,
  53                                       in ACString aMimeType,
  54                                       inout imgIContainer aContainer);
  55
  56     /**
  57      * encodeImage
  58      * Caller provides an image container, and the mime type it should be
  59      * encoded to. We return an input stream for the encoded image data.
  60      *
  61      * @param aContainer
  62      *        An image container.
  63      * @param aMimeType
  64      *        Type of encoded image desired (eg "image/png").
  65      * @param outputOptions
  66      *        Encoder-specific output options.
  67      */
  68     nsIInputStream encodeImage(in imgIContainer aContainer,
  69                                in ACString aMimeType,
  70                                [optional] in AString outputOptions);
  71
  72     /**
  73      * encodeScaledImage
  74      * Caller provides an image container, and the mime type it should be
  75      * encoded to. We return an input stream for the encoded image data.
  76      * The encoded image is scaled to the specified dimensions.
  77      *
  78      * @param aContainer
  79      *        An image container.
  80      * @param aMimeType
  81      *        Type of encoded image desired (eg "image/png").
  82      * @param aWidth, aHeight
  83      *        The size (in pixels) desired for the resulting image. Specify 0 to
  84      *        use the given image's width or height. Values must be >= 0.
  85      * @param outputOptions
  86      *        Encoder-specific output options.
  87      */
  88     nsIInputStream encodeScaledImage(in imgIContainer aContainer,
  89                                      in ACString aMimeType,
  90                                      in long aWidth,
  91                                      in long aHeight,
  92                                      [optional] in AString outputOptions);
  93
  94     /**
  95      * getImgLoaderForDocument
  96      * Retrieve an image loader that reflects the privacy status of the given
  97      * document.
  98      *
  99      * @param doc
 100      *        A document. Must not be null.
 101      */
 102     imgILoader getImgLoaderForDocument(in nsIDOMDocument doc);
 103
 104     /**
 105      * getImgLoaderForDocument
 106      * Retrieve an image cache that reflects the privacy status of the given
 107      * document.
 108      *
 109      * @param doc
 110      *        A document. Null is allowed, but must _only_ be passed
 111      *        when there is no way to obtain a relevant document for
 112      *        the current context in which a cache is desired.
 113      */
 114     imgICache getImgCacheForDocument(in nsIDOMDocument doc);
 115
 116     /**
 117      * encodeCroppedImage
 118      * Caller provides an image container, and the mime type it should be
 119      * encoded to. We return an input stream for the encoded image data.
 120      * The encoded image is cropped to the specified dimensions.
 121      *
 122      * The given offset and size must not exceed the image bounds.
 123      *
 124      * @param aContainer
 125      *        An image container.
 126      * @param aMimeType
 127      *        Type of encoded image desired (eg "image/png").
 128      * @param aOffsetX, aOffsetY
 129      *        The crop offset (in pixels). Values must be >= 0.
 130      * @param aWidth, aHeight
 131      *        The size (in pixels) desired for the resulting image. Specify 0 to
 132      *        use the given image's width or height. Values must be >= 0.
 133      * @param outputOptions
 134      *        Encoder-specific output options.
 135      */
 136     nsIInputStream encodeCroppedImage(in imgIContainer aContainer,
 137                                       in ACString aMimeType,
 138                                       in long aOffsetX,
 139                                       in long aOffsetY,
 140                                       in long aWidth,
 141                                       in long aHeight,
 142                                       [optional] in AString outputOptions);
 143
 144     /**
 145      * Create a wrapper around a scripted notification observer (ordinarily
 146      * imgINotificationObserver cannot be implemented from scripts).
 147      *
 148      * @param aObserver The scripted observer to wrap
 149      */
 150     imgINotificationObserver
 151     createScriptedObserver(in imgIScriptedNotificationObserver aObserver);
 152 };