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 "nsISupports.idl"
michael@0: 
michael@0: interface nsITransport;
michael@0: interface nsIInputStream;
michael@0: interface nsIOutputStream;
michael@0: 
michael@0: /**
michael@0:  * This service read/writes a stream on a background thread.
michael@0:  *
michael@0:  * Use this service to transform any blocking stream (e.g., file stream)
michael@0:  * into a fully asynchronous stream that can be read/written without 
michael@0:  * blocking the main thread.
michael@0:  */
michael@0: [scriptable, uuid(5e0adf7d-9785-45c3-a193-04f25a75da8f)]
michael@0: interface nsIStreamTransportService : nsISupports
michael@0: {
michael@0:     /**
michael@0:      * CreateInputTransport
michael@0:      *
michael@0:      * @param aStream
michael@0:      *        The input stream that will be read on a background thread.
michael@0:      *        This stream must implement "blocking" stream semantics.
michael@0:      * @param aStartOffset
michael@0:      *        The input stream will be read starting from this offset.  Pass
michael@0:      *        -1 to read from the current stream offset.  NOTE: this parameter
michael@0:      *        is ignored if the stream does not support nsISeekableStream.
michael@0:      * @param aReadLimit
michael@0:      *        This parameter limits the number of bytes that will be read from
michael@0:      *        the input stream.  Pass -1 to read everything.
michael@0:      * @param aCloseWhenDone
michael@0:      *        Specify this flag to have the input stream closed once its
michael@0:      *        contents have been completely read.
michael@0:      *
michael@0:      * @return nsITransport instance.
michael@0:      */
michael@0:     nsITransport createInputTransport(in nsIInputStream aStream,
michael@0:                                       in long long aStartOffset,
michael@0:                                       in long long aReadLimit,
michael@0:                                       in boolean aCloseWhenDone);
michael@0: 
michael@0:     /**
michael@0:      * CreateOutputTransport
michael@0:      *
michael@0:      * @param aStream
michael@0:      *        The output stream that will be written to on a background thread.
michael@0:      *        This stream must implement "blocking" stream semantics.
michael@0:      * @param aStartOffset
michael@0:      *        The output stream will be written starting at this offset.  Pass
michael@0:      *        -1 to write to the current stream offset.  NOTE: this parameter
michael@0:      *        is ignored if the stream does not support nsISeekableStream.
michael@0:      * @param aWriteLimit
michael@0:      *        This parameter limits the number of bytes that will be written to
michael@0:      *        the output stream.  Pass -1 for unlimited writing.
michael@0:      * @param aCloseWhenDone
michael@0:      *        Specify this flag to have the output stream closed once its
michael@0:      *        contents have been completely written.
michael@0:      *
michael@0:      * @return nsITransport instance.
michael@0:      */
michael@0:     nsITransport createOutputTransport(in nsIOutputStream aStream,
michael@0:                                        in long long aStartOffset,
michael@0:                                        in long long aWriteLimit,
michael@0:                                        in boolean aCloseWhenDone);
michael@0: };