michael@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsIStreamListener.idl"
michael@0: 
michael@0: interface nsIUnicharInputStream;
michael@0: interface nsIUnicharStreamLoader;
michael@0: interface nsIChannel;
michael@0: 
michael@0: [scriptable, uuid(c2982b39-2e48-429e-92b7-99348a1633c5)]
michael@0: interface nsIUnicharStreamLoaderObserver : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Called as soon as at least 512 octets of data have arrived.
michael@0:    * If the stream receives fewer than 512 octets of data in total,
michael@0:    * called upon stream completion but before calling OnStreamComplete.
michael@0:    * Will not be called if the stream receives no data at all.
michael@0:    *
michael@0:    * @param aLoader the unichar stream loader
michael@0:    * @param aContext the context parameter of the underlying channel
michael@0:    * @param aSegment up to 512 octets of raw data from the stream
michael@0:    *
michael@0:    * @return the name of the character set to be used to decode this stream
michael@0:    */
michael@0:   ACString onDetermineCharset(in nsIUnicharStreamLoader aLoader,
michael@0:                               in nsISupports aContext,
michael@0:                               in ACString aSegment);
michael@0: 
michael@0:   /**
michael@0:    * Called when the entire stream has been loaded and decoded.
michael@0:    *
michael@0:    * @param aLoader the unichar stream loader
michael@0:    * @param aContext the context parameter of the underlying channel
michael@0:    * @param aStatus the status of the underlying channel
michael@0:    * @param aBuffer the contents of the stream, decoded to UTF-16.
michael@0:    *
michael@0:    * This method will always be called asynchronously by the
michael@0:    * nsUnicharIStreamLoader involved, on the thread that called the
michael@0:    * loader's init() method.  If onDetermineCharset fails,
michael@0:    * onStreamComplete will still be called, but aStatus will be an
michael@0:    * error code.
michael@0:    */
michael@0:   void onStreamComplete(in nsIUnicharStreamLoader aLoader,
michael@0:                         in nsISupports aContext,
michael@0:                         in nsresult aStatus,
michael@0:                         in AString aBuffer);
michael@0: };
michael@0: 
michael@0: /**
michael@0:  * Asynchronously load a channel, converting the data to UTF-16.
michael@0:  *
michael@0:  * To use this interface, first call init() with a
michael@0:  * nsIUnicharStreamLoaderObserver that will be notified when the data has been
michael@0:  * loaded. Then call asyncOpen() on the channel with the nsIUnicharStreamLoader
michael@0:  * as the listener. The context argument in the asyncOpen() call will be
michael@0:  * passed to the onStreamComplete() callback.
michael@0:  */
michael@0: [scriptable, uuid(afb62060-37c7-4713-8a84-4a0c1199ba5c)]
michael@0: interface nsIUnicharStreamLoader : nsIStreamListener
michael@0: {
michael@0:   /**
michael@0:    * Initializes the unichar stream loader
michael@0:    *
michael@0:    * @param aObserver the observer to notify when a charset is needed and when
michael@0:    *                  the load is complete
michael@0:    */
michael@0:   void init(in nsIUnicharStreamLoaderObserver aObserver);
michael@0: 
michael@0:   /**
michael@0:    * The channel attribute is only valid inside the onDetermineCharset
michael@0:    * and onStreamComplete callbacks.  Otherwise it will be null.
michael@0:    */
michael@0:   readonly attribute nsIChannel channel;
michael@0: 
michael@0:   /**
michael@0:    * The charset that onDetermineCharset returned, if that's been
michael@0:    * called.
michael@0:    */
michael@0:   readonly attribute ACString charset;
michael@0: };