Usage of nsIStreamListener Interface

 Binds an external helper application to a stream listener. The caller
 should pump data into the returned stream listener. When the OnStopRequest
 is issued, the stream listener implementation will launch the helper app
 with this data.
 @param aMimeContentType The content type of the incoming data
 @param aRequest The request corresponding to the incoming data
 @param aWindowContext Use GetInterface to retrieve properties like the
                       dom window or parent window...
                       The service might need this in order to bring up dialogs.
 @param aForceSave True to always save this content to disk, regardless of
                   nsIMIMEInfo and other such influences.
 @return A nsIStreamListener which the caller should pump the data into.

nsIStreamListener doContent(in ACString aMimeContentType, in nsIRequest aRequest, in nsIInterfaceRequestor aWindowContext, in boolean aForceSave)

 loadImageWithChannel allows data from an existing channel to be
 used as the image data for this content node.

 @param aChannel the channel that will deliver the data

 @return a stream listener to pump the image data into

 @see imgILoader::loadImageWithChannel

 @throws NS_ERROR_NULL_POINTER if aChannel is null

nsIStreamListener loadImageWithChannel(in nsIChannel aChannel)

 Instantiate an embedded plugin for an existing channel. The caller is
 responsible for opening the channel. It may or may not be already opened
 when this function is called.

[noscript] nsIStreamListener instantiatePluginForChannel(in nsIChannel aChannel, in nsIPluginInstanceOwner aOwner)

 Create a stream listener that can be used to asynchronously
 parse RDF/XML.
 @param aSink the RDF datasource the will receive the data
 @param aBaseURI the base URI used to resolve relative
   references in the RDF/XML
 @return an nsIStreamListener object to handle the data

nsIStreamListener parseAsync(in nsIRDFDataSource aSink, in nsIURI aBaseURI)

 <b>ASYNCHRONOUS VERSION</b>
 Retrieves a nsIStreamListener that receives the original/raw data via its
 nsIStreamListener::OnDataAvailable() callback, then converts and pushes 
 the data to aListener.

 Use this method when you want to proxy (and convert) nsIStreamListener
 callbacks asynchronously.

 @param aFromType     The MIME type of the original/raw data.
 @param aToType       The MIME type of the converted data.
 @param aListener     The listener that receives the converted data.
 @param aCtxt         Either an opaque context, or a converter specific
                      context (implementation specific).
 @return              A nsIStreamListener that receives data via its
                      OnDataAvailable() method.

nsIStreamListener asyncConvertData(in string aFromType, in string aToType, in nsIStreamListener aListener, in nsISupports aContext)

 Loads data from a channel. This differs from openURI in that the channel
 may already be opened, and that it returns a stream listener into which the
 caller should pump data. The caller is responsible for opening the channel
 and pumping the channel's data into the returned stream listener.

 Note: If the channel already has a loadgroup, it will be replaced with the
 window context's load group, or null if the context doesn't have one.

 If the window context's nsIURIContentListener refuses the load immediately
 (e.g. in nsIURIContentListener::onStartURIOpen), this method will return
 NS_ERROR_WONT_HANDLE_CONTENT. At that point, the caller should probably
 cancel the channel if it's already open (this method will not cancel the
 channel).

 If flags include DONT_RETARGET, and the content listener refuses the load
 during onStartRequest (e.g. in canHandleContent/isPreferred), then the
 returned stream listener's onStartRequest method will return
 NS_ERROR_WONT_HANDLE_CONTENT.

 @param aChannel
        The channel that should be loaded. The channel may already be
        opened. It must not be closed (i.e. this must be called before the
        channel calls onStopRequest on its stream listener).
 @param aFlags
        Combination (bitwise OR) of the flags specified above. 0 indicates
        default handling.
 @param aWindowContext
        If you are running the url from a doc shell or a web shell, this is
        your window context. If you have a content listener you want to
        give first crack to, the uri loader needs to be able to get it
        from the window context. We will also be using the window context
        to get at the progress event sink interface.
        <b>Must not be null!</b>

nsIStreamListener openChannel(in nsIChannel aChannel, in unsigned long aFlags, in nsIInterfaceRequestor aWindowContext)

 Start the load and decode of an image.
 @param aChannel the channel to load the image from.  This must
                 already be opened before ths method is called, and there
                 must have been no OnDataAvailable calls for it yet.   
 @param aObserver the observer
 @param cx some random data
 @param aListener [out]
        A listener that should receive the data. Can be null, in which
        case imagelib has found a cached image and is not interested in
        the data. The caller needs not cancel the channel in this case.

 libpr0n does NOT keep a strong ref to the observer; this prevents
 reference cycles.  This means that callers of loadImageWithChannel should
 make sure to Cancel() the resulting request before the observer goes away.

[noscript] imgIRequest loadImageWithChannel(in nsIChannel aChannel, in imgIDecoderObserver aObserver, in nsISupports cx, out nsIStreamListener aListener)

 Asynchronously open this channel.  Data is fed to the specified stream
 listener as it becomes available.  The stream listener's methods are
 called on the thread that calls asyncOpen and are not called until
 after asyncOpen returns.  If asyncOpen returns successfully, the
 channel promises to call at least onStartRequest and onStopRequest.

 If the nsIRequest object passed to the stream listener's methods is not
 this channel, an appropriate onChannelRedirect notification needs to be
 sent to the notification callbacks before onStartRequest is called.
 Once onStartRequest is called, all following method calls on aListener
 will get the request that was passed to onStartRequest.

 If the channel's and loadgroup's notification callbacks do not provide
 an nsIChannelEventSink when onChannelRedirect would be called, that's
 equivalent to having called onChannelRedirect.

 If asyncOpen returns successfully, the channel is responsible for
 keeping itself alive until it has called onStopRequest on aListener or
 called onChannelRedirect.

 Implementations are allowed to synchronously add themselves to the
 associated load group (if any).

 NOTE: Implementations should throw NS_ERROR_ALREADY_OPENED if the
 channel is reopened.

 @param aListener the nsIStreamListener implementation
 @param aContext an opaque parameter forwarded to aListener's methods
 @see nsIChannelEventSink for onChannelRedirect

void asyncOpen(in nsIStreamListener aListener, in nsISupports aContext)

 asyncRead causes the input stream to be read in chunks and delivered
 asynchronously to the listener via OnDataAvailable.

 @param aListener
        receives notifications.
 @param aListenerContext
        passed to listener methods.

void asyncRead(in nsIStreamListener aListener, in nsISupports aListenerContext)

 Sets the stream listener for this plugin document 

void setStreamListener(in nsIStreamListener aStreamListener)

 <b>ASYNCRONOUS VERSION</b>
 Converts data arriving via the converter's nsIStreamListener::OnDataAvailable() 
 method from one type to another, pushing the converted data out to the caller 
 via aListener::OnDataAvailable().

 Use this method when you want to proxy (and convert) nsIStreamListener callbacks
 asynchronously.

 @param aFromType     The MIME type of the original/raw data.
 @param aToType       The MIME type of the converted data.
 @param aListener     The listener who receives the converted data.
 @param aCtxt         Either an opaque context, or a converter specific context
                      (implementation specific).

void asyncConvertData(in string aFromType, in string aToType, in nsIStreamListener aListener, in nsISupports aCtxt)

 <b>ASYNCHRONOUS VERSION</b>
 Retrieves a nsIStreamListener that receives the original/raw data via its
 nsIStreamListener::OnDataAvailable() callback, then converts and pushes 
 the data to aListener.

 Use this method when you want to proxy (and convert) nsIStreamListener
 callbacks asynchronously.

 @param aFromType     The MIME type of the original/raw data.
 @param aToType       The MIME type of the converted data.
 @param aListener     The listener that receives the converted data.
 @param aCtxt         Either an opaque context, or a converter specific
                      context (implementation specific).
 @return              A nsIStreamListener that receives data via its
                      OnDataAvailable() method.

nsIStreamListener asyncConvertData(in string aFromType, in string aToType, in nsIStreamListener aListener, in nsISupports aContext)

 Notifies the content listener to hook up an nsIStreamListener capable of
 consuming the data stream.

 @param aContentType         Content type of the data.
 @param aIsContentPreferred  Indicates whether the content should be
                             preferred by this listener.
 @param aRequest             Request that is providing the data.
 @param aContentHandler      nsIStreamListener that will consume the data.
                             This should be set to <code>nsnull</code> if
                             this content listener can't handle the content
                             type.

 @return                     <code>true</code> if the consumer wants to
                             handle the load completely by itself.  This
                             causes the URI Loader do nothing else...
                             <code>false</code> if the URI Loader should
                             continue handling the load and call the
                             returned streamlistener's methods. 

boolean doContent(in string aContentType, in boolean aIsContentPreferred, in nsIRequest aRequest, out nsIStreamListener aContentHandler)