nsIStreamConverter.idl (5041B)
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 "nsIThreadRetargetableStreamListener.idl" 7 8 interface nsIChannel; 9 interface nsIInputStream; 10 11 /** 12 * nsIStreamConverter provides an interface to implement when you have code 13 * that converts data from one type to another. 14 * 15 * Suppose you had code that converted plain text into HTML. You could implement 16 * this interface to allow everyone else to use your conversion logic using a 17 * standard api. 18 * <p> 19 * <b>STREAM CONVERTER USERS</b> 20 * 21 * There are currently two ways to use a stream converter: 22 * <ol> 23 * <li> <b>SYNCHRONOUS</b> Stream to Stream 24 * You can supply the service with a stream of type X 25 * and it will convert it to your desired output type and return 26 * a converted (blocking) stream to you.</li> 27 * 28 * <li> <b>ASYNCHRONOUS</b> nsIStreamListener to nsIStreamListener 29 * You can supply data directly to the converter by calling it's 30 * nsIStreamListener::OnDataAvailable() method. It will then 31 * convert that data from type X to your desired output type and 32 * return converted data to you via the nsIStreamListener you passed 33 * in by calling its OnDataAvailable() method.</li> 34 * </ol> 35 * <p> 36 * 37 * <b>STREAM CONVERTER SUPPLIERS</b> 38 * 39 * Registering a stream converter: 40 * Stream converter registration is a two step process. First of all the stream 41 * converter implementation must register itself with the component manager using 42 * a contractid in the format below. Second, the stream converter must add the contractid 43 * to the registry. 44 * 45 * Stream converter contractid format (the stream converter root key is defined in this 46 * file): 47 * 48 * <pre>@mozilla.org/streamconv;1?from=FROM_MIME_TYPE&to=TO_MIME_TYPE</pre> 49 * 50 * @author Jud Valeski 51 * @see nsIStreamConverterService 52 */ 53 54 [scriptable, uuid(0b6e2c69-5cf5-48b0-9dfd-c95950e2cc7b)] 55 interface nsIStreamConverter : nsIThreadRetargetableStreamListener { 56 57 /** 58 * <b>SYNCRONOUS VERSION</b> 59 * Converts a stream of one type, to a stream of another type. 60 * 61 * Use this method when you have a stream you want to convert. 62 * 63 * @param aFromStream The stream representing the original/raw data. 64 * @param aFromType The MIME type of aFromStream. 65 * @param aToType The MIME type of the returned stream. 66 * @param aCtxt Either an opaque context, or a converter specific context 67 * (implementation specific). 68 * @return The converted stream. NOTE: The returned stream may not 69 * already be converted. An efficient stream converter 70 * implementation will converter data on demand rather than 71 * buffering the converted data until it is used. 72 */ 73 nsIInputStream convert(in nsIInputStream aFromStream, 74 in string aFromType, 75 in string aToType, 76 in nsISupports aCtxt); 77 78 /** 79 * <b>ASYNCRONOUS VERSION</b> 80 * Converts data arriving via the converter's nsIStreamListener::OnDataAvailable() 81 * method from one type to another, pushing the converted data out to the caller 82 * via aListener::OnDataAvailable(). 83 * 84 * Use this method when you want to proxy (and convert) nsIStreamListener callbacks 85 * asynchronously. 86 * 87 * @param aFromType The MIME type of the original/raw data. 88 * @param aToType The MIME type of the converted data. 89 * @param aListener The listener who receives the converted data. 90 * @param aCtxt Either an opaque context, or a converter specific context 91 * (implementation specific). 92 */ 93 void asyncConvertData(in string aFromType, 94 in string aToType, 95 in nsIStreamListener aListener, 96 in nsISupports aCtxt); 97 98 /** 99 * This is called after the request has installed the stream converter as its listener 100 * giving the stream converter the option to request retargetting of onDataAvailable. 101 */ 102 void maybeRetarget(in nsIRequest request); 103 104 /** 105 * Returns the content type that the stream listener passed to asyncConvertData will 106 * see on the channel if the conversion is being done from aFromType to * /*. 107 * 108 * @param aFromType The type of the content prior to conversion. 109 * @param aChannel The channel that we'd like to convert. May be null. 110 * 111 * @throws if the converter does not support conversion to * /* or if it doesn't know 112 * the type in advance. 113 */ 114 ACString getConvertedType(in ACString aFromType, in nsIChannel aChannel); 115 }; 116 117 %{C++ 118 #define NS_ISTREAMCONVERTER_KEY "@mozilla.org/streamconv;1" 119 %}