1 /* ***** BEGIN LICENSE BLOCK *****
2 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
3 *
4 * The contents of this file are subject to the Mozilla Public License Version
5 * 1.1 (the "License"); you may not use this file except in compliance with
6 * the License. You may obtain a copy of the License at
7 * http://www.mozilla.org/MPL/
8 *
9 * Software distributed under the License is distributed on an "AS IS" basis,
10 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
11 * for the specific language governing rights and limitations under the
12 * License.
13 *
14 * The Original Code is Mozilla.
15 *
16 * The Initial Developer of the Original Code is
17 * Netscape Communications Corporation.
18 * Portions created by the Initial Developer are Copyright (C) 2002
19 * the Initial Developer. All Rights Reserved.
20 *
21 * Contributor(s):
22 * Darin Fisher <darin@netscape.com>
23 * Christian Biesinger <cbiesinger@web.de>
24 *
25 * Alternatively, the contents of this file may be used under the terms of
26 * either the GNU General Public License Version 2 or later (the "GPL"), or
27 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
28 * in which case the provisions of the GPL or the LGPL are applicable instead
29 * of those above. If you wish to allow use of your version of this file only
30 * under the terms of either the GPL or the LGPL, and not to allow others to
31 * use your version of this file under the terms of the MPL, indicate your
32 * decision by deleting the provisions above and replace them with the notice
33 * and other provisions required by the GPL or the LGPL. If you do not delete
34 * the provisions above, a recipient may use your version of this file under
35 * the terms of any one of the MPL, the GPL or the LGPL.
36 *
37 * ***** END LICENSE BLOCK ***** */
38
39 #include "nsIRequest.idl"
40
41 interface nsIInputStream;
42 interface nsIStreamListener;
43
44 /**
45 * nsIInputStreamPump
46 *
47 * This interface provides a means to configure and use a input stream pump
48 * instance. The input stream pump will asynchronously read from a input
49 * stream, and push data to a nsIStreamListener instance. It utilizes the
50 * current thread's nsIEventTarget in order to make reading from the stream
51 * asynchronous.
52 *
53 * If the given stream supports nsIAsyncInputStream, then the stream pump will
54 * call the stream's AsyncWait method to drive the stream listener. Otherwise,
55 * the stream will be read on a background thread utilizing the stream
56 * transport service. More details are provided below.
57 */
58 [scriptable, uuid(400F5468-97E7-4d2b-9C65-A82AECC7AE82)]
59 interface nsIInputStreamPump : nsIRequest
60 {
61 /**
62 * Initialize the input stream pump.
63 *
64 * @param aStream
65 * contains the data to be read. if the input stream is non-blocking,
66 * then it will be QI'd to nsIAsyncInputStream. if the QI succeeds
67 * then the stream will be read directly. otherwise, it will be read
68 * on a background thread using the stream transport service.
69 * @param aStreamPos
70 * specifies the stream offset from which to start reading. the
71 * offset value is absolute. pass -1 to specify the current offset.
72 * NOTE: this parameter is ignored if the underlying stream does not
73 * implement nsISeekableStream.
74 * @param aStreamLen
75 * specifies how much data to read from the stream. pass -1 to read
76 * all data available in the stream.
77 * @param aSegmentSize
78 * if the stream transport service is used, then this parameter
79 * specifies the segment size for the stream transport's buffer.
80 * pass 0 to specify the default value.
81 * @param aSegmentCount
82 * if the stream transport service is used, then this parameter
83 * specifies the segment count for the stream transport's buffer.
84 * pass 0 to specify the default value.
85 * @param aCloseWhenDone
86 * if true, the input stream will be closed after it has been read.
87 */
88 void init(in nsIInputStream aStream,
89 in long long aStreamPos,
90 in long long aStreamLen,
91 in unsigned long aSegmentSize,
92 in unsigned long aSegmentCount,
93 in boolean aCloseWhenDone);
94
95 /**
96 * asyncRead causes the input stream to be read in chunks and delivered
97 * asynchronously to the listener via OnDataAvailable.
98 *
99 * @param aListener
100 * receives notifications.
101 * @param aListenerContext
102 * passed to listener methods.
103 */
104 void asyncRead(in nsIStreamListener aListener,
105 in nsISupports aListenerContext);
106 };