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