OLD | NEW |
| (Empty) |
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | |
2 // for details. All rights reserved. Use of this source code is governed by a | |
3 // BSD-style license that can be found in the LICENSE file. | |
4 | |
5 /** | |
6 * Output streams are used to write data sequentially to a data | |
7 * destination e.g. a connected socket or an open file. | |
8 * | |
9 * An output stream provides internal buffering of the data written | |
10 * through all calls to [write] and [writeFrom] if data cannot be | |
11 * written immediately to the communication channel. The callback set | |
12 * through [onNoPendingWrites] can be used to to keep the rate of | |
13 * writing in sync with the rate the system can actually write data to | |
14 * the underlying communication channel. | |
15 */ | |
16 abstract class OutputStream { | |
17 /** | |
18 * Writes the content of [buffer] to the stream. If [copyBuffer] is | |
19 * false ownership of the specified buffer is passed to the system | |
20 * and the caller should not change it afterwards. The default value | |
21 * for [copyBuffer] is true. | |
22 * | |
23 * Returns true if the data could be written to the underlying | |
24 * communication channel immediately. Otherwise the data is buffered | |
25 * by the output stream and will be sent as soon as possible. | |
26 */ | |
27 bool write(List<int> buffer, [bool copyBuffer]); | |
28 | |
29 /** | |
30 * Writes [len] bytes from buffer [buffer] starting at offset | |
31 * [offset] to the output stream. If [offset] is not specified the | |
32 * default is 0. If [len] is not specified the default is the length | |
33 * of the buffer minus [offset] (i.e. writing from offset to the end | |
34 * of the buffer). The system will copy the data to be written so | |
35 * the caller can safely change [buffer] afterwards. | |
36 * | |
37 * Returns true if the data could be written to the underlying | |
38 * communication channel immediately. Otherwise the data is buffered | |
39 * by the output stream and will be sent as soon as possible. | |
40 */ | |
41 bool writeFrom(List<int> buffer, [int offset, int len]); | |
42 | |
43 /** | |
44 * Write a string to the stream using the given [encoding].The | |
45 * default encoding is UTF-8 - [:Encoding.UTF_8:]. | |
46 * | |
47 * Returns true if the data could be written to the underlying | |
48 * communication channel immediately. Otherwise the data is buffered | |
49 * by the output stream and will be sent as soon as possible. | |
50 */ | |
51 bool writeString(String string, [Encoding encoding]); | |
52 | |
53 /** | |
54 * Flushes data from any internal buffers as soon as possible. Note | |
55 * that the actual meaning of calling [flush] will depend on the | |
56 * actual type of the underlying communication channel. | |
57 */ | |
58 void flush(); | |
59 | |
60 /** | |
61 * Signal that no more data will be written to the output stream. When all | |
62 * buffered data has been written out to the communication channel, the | |
63 * channel will be closed and the [onClosed] callback will be called. | |
64 */ | |
65 void close(); | |
66 | |
67 /** | |
68 * Close the communication channel immediately ignoring any buffered | |
69 * data. | |
70 */ | |
71 void destroy(); | |
72 | |
73 /** | |
74 * Returns whether the stream has been closed by calling close(). If true, no | |
75 * more data may be written to the output stream, but there still may be | |
76 * buffered data that has not been written to the communication channel. The | |
77 * onClosed handler will only be called once all data has been written out. | |
78 */ | |
79 bool get closed; | |
80 | |
81 /** | |
82 * Sets the handler that gets called when the internal OS buffers | |
83 * have been flushed. This callback can be used to keep the rate of | |
84 * writing in sync with the rate the system can write data to the | |
85 * underlying communication channel. | |
86 */ | |
87 void set onNoPendingWrites(void callback()); | |
88 | |
89 /** | |
90 * Sets the handler that gets called when the underlying communication channel | |
91 * has been closed and all the buffered data has been sent. | |
92 */ | |
93 void set onClosed(void callback()); | |
94 | |
95 /** | |
96 * Sets the handler that gets called when the underlying | |
97 * communication channel gets into some kind of error situation. | |
98 */ | |
99 void set onError(void callback(e)); | |
100 } | |
101 | |
OLD | NEW |