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/. */
6 #include
"nsIThreadRetargetableStreamListener.idl"
9 interface nsIInputStream
;
12 * nsIStreamConverter provides an interface to implement when you have code
13 * that converts data from one type to another.
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
19 * <b>STREAM CONVERTER USERS</b>
21 * There are currently two ways to use a stream converter:
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>
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>
37 * <b>STREAM CONVERTER SUPPLIERS</b>
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
45 * Stream converter contractid format (the stream converter root key is defined in this
48 * <pre>@mozilla.org/streamconv;1?from=FROM_MIME_TYPE&to=TO_MIME_TYPE</pre>
51 * @see nsIStreamConverterService
54 [scriptable
, uuid(0b6e2c69
-5cf5
-48b0
-9dfd
-c95950e2cc7b
)]
55 interface nsIStreamConverter
: nsIThreadRetargetableStreamListener
{
58 * <b>SYNCRONOUS VERSION</b>
59 * Converts a stream of one type, to a stream of another type.
61 * Use this method when you have a stream you want to convert.
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.
73 nsIInputStream convert
(in nsIInputStream aFromStream
,
76 in nsISupports aCtxt
);
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().
84 * Use this method when you want to proxy (and convert) nsIStreamListener callbacks
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).
93 void asyncConvertData
(in string aFromType
,
95 in nsIStreamListener aListener
,
96 in nsISupports aCtxt
);
99 * Returns the content type that the stream listener passed to asyncConvertData will
100 * see on the channel if the conversion is being done from aFromType to * /*.
102 * @param aFromType The type of the content prior to conversion.
103 * @param aChannel The channel that we'd like to convert. May be null.
105 * @throws if the converter does not support conversion to * /* or if it doesn't know
106 * the type in advance.
108 ACString getConvertedType
(in ACString aFromType
, in nsIChannel aChannel
);
112 #define NS_ISTREAMCONVERTER_KEY
"@mozilla.org/streamconv;1"