| // 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. |
| |
| /** |
| * Basic input stream which supplies binary data. |
| * |
| * Input streams are used to read data sequentially from some data |
| * source. All input streams are non-blocking. They each have a number |
| * of read calls which will always return without any IO related |
| * blocking. If the requested data is not available a read call will |
| * return `null`. All input streams have one or more handlers which |
| * will trigger when data is available. |
| * |
| * The following example shows a data handler in an ordinary input |
| * stream which will be called when some data is available and a call |
| * to read will not return `null`. |
| * |
| * InputStream input = ... |
| * input.onData = () { |
| * var data = input.read(); |
| * ... |
| * }; |
| * |
| * If for some reason the data from an input stream cannot be handled |
| * by the application immediately setting the data handler to `null` |
| * will avoid further callbacks until it is set to a function |
| * again. While the data handler is not active system flow control |
| * will be used to avoid buffering more data than needed. |
| * |
| * Always set up appropriate handlers when using input streams. |
| * |
| */ |
| abstract class InputStream { |
| /** |
| * Reads data from the stream. Returns a system allocated buffer |
| * with up to [len] bytes. If no value is passed for [len] all |
| * available data will be returned. If no data is available null will |
| * be returned. |
| */ |
| List<int> read([int len]); |
| |
| /** |
| * Reads up to [len] bytes into buffer [buffer] starting at offset |
| * [offset]. Returns the number of bytes actually read which might |
| * be zero. If [offset] is not specified 0 is used. If [len] is not |
| * specified the length of [buffer] is used. |
| */ |
| int readInto(List<int> buffer, [int offset, int len]); |
| |
| /** |
| * Returns the number of bytes available for immediate reading. |
| */ |
| int available(); |
| |
| /** |
| * Pipe the content of this input stream directly to the output |
| * stream [output]. The default behavior is to close the output when |
| * all the data from the input stream have been written. Specifying |
| * `false` for the optional argument [close] keeps the output |
| * stream open after writing all data from the input stream. |
| */ |
| void pipe(OutputStream output, {bool close: true}); |
| |
| /** |
| * Close the underlying communication channel to avoid getting any |
| * more data. In normal situations, where all data is read from the |
| * stream until the close handler is called, calling [close] is not |
| * required. When [close] is used the close handler will still be |
| * called. |
| */ |
| void close(); |
| |
| /** |
| * Returns whether the stream is closed. There will be no more data |
| * to read. |
| */ |
| bool get closed; |
| |
| /** |
| * Sets the handler that gets called when data is available. |
| */ |
| void set onData(void callback()); |
| |
| /** |
| * Sets the handler that gets called when there will be no more data |
| * available in the stream. |
| */ |
| 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)); |
| } |
| |
| |
| /** |
| * String encodings. |
| */ |
| class Encoding { |
| static const Encoding UTF_8 = const Encoding._internal("UTF-8"); |
| static const Encoding ISO_8859_1 = const Encoding._internal("ISO-8859-1"); |
| static const Encoding ASCII = const Encoding._internal("ASCII"); |
| const Encoding._internal(String this.name); |
| final String name; |
| } |
| |
| |
| /** |
| * A string input stream wraps a basic input stream and supplies |
| * string data. This data can be read either as string chunks or as |
| * lines separated by line termination character sequences. |
| */ |
| abstract class StringInputStream { |
| /** |
| * Decodes a binary input stream into characters using the specified |
| * encoding. |
| */ |
| factory StringInputStream(InputStream input, |
| [Encoding encoding = Encoding.UTF_8]) { |
| return new _StringInputStream(input, encoding); |
| } |
| |
| /** |
| * Reads up to [len] characters from the stream. if [len] is not |
| * specified reads as many characters as is available from the |
| * stream. If no data is available null will be returned. |
| */ |
| String read([int len]); |
| |
| /** |
| * Reads the next line from the stream. The line ending characters |
| * will not be part of the returned string. If a full line is not |
| * available null will be returned. |
| */ |
| String readLine(); |
| |
| /** |
| * Returns the number of characters available for immediate |
| * reading. Note that this includes all characters that will be in |
| * the String returned from [read] this includes line breaking |
| * characters. If [readLine] is used for reading one can observe |
| * less characters being returned as the line breaking characters |
| * are discarded. |
| */ |
| int available(); |
| |
| /** |
| * Returns whether the stream has been closed. There might still be |
| * more data to read. |
| */ |
| bool get closed; |
| |
| /** |
| * Returns the encoding used to decode the binary data into characters. |
| */ |
| Encoding get encoding; |
| |
| /** |
| * Sets the handler that gets called when data is available. The two |
| * handlers [onData] and [onLine] are mutually exclusive |
| * and setting one will remove the other. |
| */ |
| void set onData(void callback()); |
| |
| /** |
| * Sets the handler that gets called when a line is available. The |
| * two handlers [onData] and [onLine] are mutually |
| * exclusive and setting one will remove the other. |
| */ |
| void set onLine(void callback()); |
| |
| /** |
| * Sets the handler that gets called when there will be no more data |
| * available in the stream. |
| */ |
| 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)); |
| } |
| |
| |
| /** |
| * A chunked input stream wraps a basic input stream and supplies |
| * binary data in configurable chunk sizes. |
| */ |
| abstract class ChunkedInputStream { |
| /** |
| * Adds buffering to an input stream and provide the ability to read |
| * the data in known size chunks. |
| */ |
| factory ChunkedInputStream(InputStream input, [int chunkSize = 0]) { |
| return new _ChunkedInputStream(input, chunkSize); |
| } |
| |
| /** |
| * Reads [chunkSize] bytes from the stream. If [chunkSize] bytes are |
| * not currently available null is returned. When the stream is |
| * closed the last call can return with less than [chunkSize] bytes. |
| */ |
| List<int> read(); |
| |
| /** |
| * Returns whether the stream has been closed. There might still be |
| * more data to read. |
| */ |
| bool get closed; |
| |
| /** |
| * Returns the chunk size used by this stream. |
| */ |
| int get chunkSize; |
| |
| /** |
| * Sets the chunk size used by this stream. |
| */ |
| void set chunkSize(int chunkSize); |
| |
| /** |
| * Sets the handler that gets called when at least [chunkSize] bytes |
| * of data is available or the underlying stream has been closed and |
| * there is still unread data. |
| */ |
| void set onData(void callback()); |
| |
| /** |
| * Sets the handler that gets called when there will be no more data |
| * available in the stream. |
| */ |
| 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)); |
| } |
| |
| |
| class StreamException implements Exception { |
| const StreamException([String this.message = ""]); |
| const StreamException.streamClosed() : message = "Stream closed"; |
| String toString() => "StreamException: $message"; |
| final String message; |
| } |