| // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file |
| // for details. All rights reserved. Use of this source code is governed by a |
| // BSD-style license that can be found in the LICENSE file. |
| |
| /** |
| * Output streams are used to write data sequentially to a data |
| * destination e.g. a connected socket or an open file. |
| * |
| * An output stream provides internal buffering of the data written |
| * through all calls to [write] and [writeFrom] if data cannot be |
| * written immediately to the communication channel. The callback set |
| * through [onNoPendingWrites] can be used to to keep the rate of |
| * writing in sync with the rate the system can actually write data to |
| * the underlying communication channel. |
| */ |
| abstract class OutputStream { |
| /** |
| * Writes the content of [buffer] to the stream. If [copyBuffer] is |
| * false ownership of the specified buffer is passed to the system |
| * and the caller should not change it afterwards. The default value |
| * for [copyBuffer] is true. |
| * |
| * Returns true if the data could be written to the underlying |
| * communication channel immediately. Otherwise the data is buffered |
| * by the output stream and will be sent as soon as possible. |
| */ |
| bool write(List<int> buffer, [bool copyBuffer]); |
| |
| /** |
| * Writes [len] bytes from buffer [buffer] starting at offset |
| * [offset] to the output stream. If [offset] is not specified the |
| * default is 0. If [len] is not specified the default is the length |
| * of the buffer minus [offset] (i.e. writing from offset to the end |
| * of the buffer). The system will copy the data to be written so |
| * the caller can safely change [buffer] afterwards. |
| * |
| * Returns true if the data could be written to the underlying |
| * communication channel immediately. Otherwise the data is buffered |
| * by the output stream and will be sent as soon as possible. |
| */ |
| bool writeFrom(List<int> buffer, [int offset, int len]); |
| |
| /** |
| * Write a string to the stream using the given [encoding].The |
| * default encoding is UTF-8 - [:Encoding.UTF_8:]. |
| * |
| * Returns true if the data could be written to the underlying |
| * communication channel immediately. Otherwise the data is buffered |
| * by the output stream and will be sent as soon as possible. |
| */ |
| bool writeString(String string, [Encoding encoding]); |
| |
| /** |
| * Flushes data from any internal buffers as soon as possible. Note |
| * that the actual meaning of calling [flush] will depend on the |
| * actual type of the underlying communication channel. |
| */ |
| void flush(); |
| |
| /** |
| * Signal that no more data will be written to the output stream. When all |
| * buffered data has been written out to the communication channel, the |
| * channel will be closed and the [onClosed] callback will be called. |
| */ |
| void close(); |
| |
| /** |
| * Close the communication channel immediately ignoring any buffered |
| * data. |
| */ |
| void destroy(); |
| |
| /** |
| * Returns whether the stream has been closed by calling close(). If true, no |
| * more data may be written to the output stream, but there still may be |
| * buffered data that has not been written to the communication channel. The |
| * onClosed handler will only be called once all data has been written out. |
| */ |
| bool get closed; |
| |
| /** |
| * Sets the handler that gets called when the internal OS buffers |
| * have been flushed. This callback can be used to keep the rate of |
| * writing in sync with the rate the system can write data to the |
| * underlying communication channel. |
| */ |
| void set onNoPendingWrites(void callback()); |
| |
| /** |
| * Sets the handler that gets called when the underlying communication channel |
| * has been closed and all the buffered data has been sent. |
| */ |
| void set onClosed(void callback()); |
| |
| /** |
| * Sets the handler that gets called when the underlying |
| * communication channel gets into some kind of error situation. |
| */ |
| void set onError(void callback(e)); |
| } |
| |