nsIStreamConverterService.idl (3881B)
1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ 2 /* This Source Code Form is subject to the terms of the Mozilla Public 3 * License, v. 2.0. If a copy of the MPL was not distributed with this 4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 5 6 #include "nsISupports.idl" 7 8 interface nsIChannel; 9 interface nsIInputStream; 10 interface nsIStreamListener; 11 12 %{C++ 13 #define NS_ISTREAMCONVERTER_KEY "@mozilla.org/streamconv;1" 14 %} 15 16 /** 17 * The nsIStreamConverterService is a higher level stream converter factory 18 * responsible for locating and creating stream converters 19 * (nsIStreamConverter). 20 * 21 * This service retrieves an interface that can convert data from a particular 22 * MIME type, to a particular MIME type. It is responsible for any intermediary 23 * conversion required in order to get from X to Z, assuming direct conversion 24 * is not possible. 25 * 26 * @author Jud Valeski 27 * @see nsIStreamConverter 28 */ 29 [scriptable, uuid(f2b1ab53-f0bd-4adb-9365-e59b1701a258)] 30 interface nsIStreamConverterService : nsISupports { 31 /** 32 * Tests whether conversion between the two specified types is possible. 33 * This is cheaper than calling convert()/asyncConvertData(); it is not 34 * necessary to call this function before calling one of those, though. 35 */ 36 boolean canConvert(in string aFromType, in string aToType); 37 38 /** 39 * Returns the content type that will be returned from a converter 40 * created with aFromType and * /*. 41 * Can fail if no converters support this conversion, or if the 42 * output type isn't known in advance. 43 */ 44 ACString convertedType(in ACString aFromType, in nsIChannel aChannel); 45 46 /** 47 * <b>SYNCHRONOUS VERSION</b> 48 * Converts a stream of one type, to a stream of another type. 49 * 50 * Use this method when you have a stream you want to convert. 51 * 52 * @param aFromStream The stream representing the original/raw data. 53 * @param aFromType The MIME type of aFromStream. 54 * @param aToType The MIME type of the returned stream. 55 * @param aContext Either an opaque context, or a converter specific 56 * context (implementation specific). 57 * @return The converted stream. NOTE: The returned stream 58 * may not already be converted. An efficient stream 59 * converter implementation will convert data on 60 * demand rather than buffering the converted data 61 * until it is used. 62 */ 63 nsIInputStream convert(in nsIInputStream aFromStream, 64 in string aFromType, 65 in string aToType, 66 in nsISupports aContext); 67 68 /** 69 * <b>ASYNCHRONOUS VERSION</b> 70 * Retrieves a nsIStreamListener that receives the original/raw data via its 71 * nsIStreamListener::OnDataAvailable() callback, then converts and pushes 72 * the data to aListener. 73 * 74 * Use this method when you want to proxy (and convert) nsIStreamListener 75 * callbacks asynchronously. 76 * 77 * @param aFromType The MIME type of the original/raw data. 78 * @param aToType The MIME type of the converted data. 79 * @param aListener The listener that receives the converted data. 80 * @param aCtxt Either an opaque context, or a converter specific 81 * context (implementation specific). 82 * @return A nsIStreamListener that receives data via its 83 * OnDataAvailable() method. 84 */ 85 nsIStreamListener asyncConvertData(in string aFromType, 86 in string aToType, 87 in nsIStreamListener aListener, 88 in nsISupports aContext); 89 };