#include "nsIStreamListener.idl"
#include "nsIInputStream.idl"
#include "nsIURI.idl"

////////////////////////////////////////////////////////////////////////////
// STREAM CONVERTER USERS
////////////////////////////////////////////////////////////////////////////

// There are currently two ways to use a stream converter:
// 1. SYNCRONOUS. Stream to Stream.
//    You can supply the service with a stream of type X
//    and it will convert it to your desired output type and return
//    a converted stream to you.
// 
//
// 3. ASYNCRONOUS. nsIStreamListener to nsIStreamListener
//    You can supply data directly to the converter by calling it's
//    nsIStreamListener::OnDataAvailable() method. It will then
//    convert that data from type X to your desired output type and
//    return converted data to you via the nsIStreamListener you passed
//    in by calling its OnDataAvailable() method.

////////////////////////////////////////////////////////////////////////////
// STREAM CONVERTER SUPPLIERS
////////////////////////////////////////////////////////////////////////////

// Registering a stream converter.
// Stream converter registration is a two step process. First of all the stream
// converter implementation must register itself with the component manager using
// a progid in the format below. Second, the stream converter must add the progid
// to the registry.
//
// Stream converter progid format (the stream converter root key is defined in this
// file):
//
// Software/Netscape/streamconv/?from=FROM_MIME_TYPE?to=TO_MIME_TYPE

[scriptable, uuid(46484B30-3BD2-11d3-A16C-0050041CAF44)]
interface nsIStreamConverter : nsIStreamListener {
	
    // SYNCRONOUS VERSION

	// Converts aFromStream of type aFromType, to a resulting stream of type aToType.
	// Use this when you have a stream as input.
    nsIInputStream Convert(in nsIInputStream aFromStream,
						   in wstring aFromType,
						   in wstring aToType,
                           in nsISupports aCtxt);

	// ASYNCRONOUS VERSION

	// Converts data arriving via the converter's nsIStreamListener::OnDataAvailable() method
	// from type aFromType to aToType pushing the converted data out to the caller via
	// aListener::OnDataAvailable().
	void AsyncConvertData(in wstring aFromType,
				 in wstring aToType,
				 in nsIStreamListener aListener,
                 in nsISupports aCtxt);
};

%{C++
#define NS_ISTREAMCONVERTER_KEY         "Software/Netscape/streamconv/"
%}