imgITools.idl (7954B)
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 };