OLD | NEW |
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | 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 | 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. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 /** | 5 /** |
6 * File, socket, HTTP, and other I/O support for server applications. | 6 * File, socket, HTTP, and other I/O support for server applications. |
7 * | 7 * |
8 * The IO library is used for Dart server applications, | 8 * The I/O library is used for Dart server applications, |
9 * which run on a stand-alone Dart VM from the command line. | 9 * which run on a stand-alone Dart VM from the command line. |
10 * *This library does not work in browser based applications.* | 10 * *This library does not work in browser-based applications.* |
11 * | 11 * |
12 * This library allows you to work with files, directories, | 12 * This library allows you to work with files, directories, |
13 * sockets, processes, HTTP servers and clients, and more. | 13 * sockets, processes, HTTP servers and clients, and more. |
| 14 * |
| 15 * To use this library in your code: |
| 16 * |
| 17 * import 'dart:io'; |
| 18 * |
| 19 * *Note:* Many operations related to input and output are asynchronous |
| 20 * and are handled using [Future]s or [Stream]s, both of which |
| 21 * are defined in the `dart:async` library. |
| 22 * |
| 23 * ## File, Directory, and Link |
| 24 * |
| 25 * An instance of [File], [Directory], or [Link] represents a file, |
| 26 * directory, or link, respectively, in the native file system. |
| 27 * |
| 28 * You can manipulate the file system through objects of these types. |
| 29 * For example, you can rename a file or directory: |
| 30 * |
| 31 * File myFile = new File('myFile.txt'); |
| 32 * myFile.rename('yourFile.txt').then((_) => print('file renamed')); |
| 33 * |
| 34 * Many methods provided by the File, Directory, and Link classes |
| 35 * run asynchronously and return a Future. |
| 36 * |
| 37 * ## FileSystemEntity |
| 38 * |
| 39 * File, Directory, and Link all extend [FileSystemEntity]. |
| 40 * In addition to being the superclass for these classes, |
| 41 * FileSystemEntity has a number of static methods for working with paths. |
| 42 * |
| 43 * To get information about a path, |
| 44 * you can use the FileSystemEntity static methods |
| 45 * such as 'isDirectory', 'isFile', and 'exists'. |
| 46 * Because file system access involves I/O, these methods |
| 47 * are asynchronous and return a Future. |
| 48 * |
| 49 * FileSystemEntity.isDirectory(myPath).then((isDir) { |
| 50 * if (isDir) { |
| 51 * print('$myPath is a directory'); |
| 52 * } else { |
| 53 * print('$myPath is not a directory'); |
| 54 * } |
| 55 * }); |
| 56 * |
| 57 * ## HttpServer and HttpClient |
| 58 * |
| 59 * The classes [HttpServer] and [HttpClient] |
| 60 * provide HTTP server and HTTP client functionality. |
| 61 * |
| 62 * The [HttpServer] class provides the basic functionality for |
| 63 * implementing an HTTP server. |
| 64 * For some higher-level building-blocks, we recommend that you try |
| 65 * the [http_server](https://pub.dartlang.org/packages/http_server) |
| 66 * pub package, which contains |
| 67 * a set of high-level classes that, together with the [HttpServer] class |
| 68 * in this library, make it easier to implement HTTP servers. |
| 69 * |
| 70 * ## Process |
| 71 * |
| 72 * The [Process] class provides a way to run a process on |
| 73 * the native machine. |
| 74 * For example, the following code spawns a process that recursively lists |
| 75 * the files under `web`. |
| 76 * |
| 77 * Process.start('ls', ['-R', 'web']).then((process) { |
| 78 * stdout.addStream(process.stdout); |
| 79 * stderr.addStream(process.stderr); |
| 80 * process.exitCode.then(print); |
| 81 * }); |
| 82 * |
| 83 * Using `start()` returns a Future, which completes with a [Process] object whe
n |
| 84 * the process has started. This [Process] object allows you to interact with th
e |
| 85 * process while it is running. Using `run()` returns a Future, which completes
with |
| 86 * a [ProcessResult] object when the spawned process has terminated. This |
| 87 * [ProcessResult] object collects the output and exit code from the process. |
| 88 * |
| 89 * When using `start()`, |
| 90 * you need to read all data coming on the stdout and stderr streams otherwise |
| 91 * the system resources will not be freed. |
| 92 * |
| 93 * ## WebSocket |
| 94 * |
| 95 * The [WebSocket] class provides support for the web socket protocol. This allo
ws |
| 96 * full-duplex communications between client and server applications. |
| 97 * Use the WebSocket class in the `dart:html` library for web clients. |
| 98 * |
| 99 * A web socket server uses a normal HTTP server for accepting web socket |
| 100 * connections. The initial handshake is a HTTP request which is then upgraded t
o a |
| 101 * web socket connection. |
| 102 * The server upgrades the request using [WebSocketTransformer] |
| 103 * and listens for the data on the returned web socket. |
| 104 * For example, here's a mini server that listens for 'ws' data |
| 105 * on a WebSocket: |
| 106 * |
| 107 * runZoned(() { |
| 108 * HttpServer.bind('127.0.0.1', 4040).then((server) { |
| 109 * server.listen((HttpRequest req) { |
| 110 * if (req.uri.path == '/ws') { |
| 111 * WebSocketTransformer.upgrade(req).then((socket) { |
| 112 * socket.listen(handleMsg); |
| 113 * }); |
| 114 * } |
| 115 * }); |
| 116 * }); |
| 117 * }, |
| 118 * onError: (e) => print("An error occurred.")); |
| 119 * |
| 120 * The client connects to the WebSocket using the `connect()` method |
| 121 * and a URI that uses the Web Socket protocol. |
| 122 * The the client can write to the WebSocket with the `add()` method. |
| 123 * For example, |
| 124 * |
| 125 * WebSocket.connect('ws://127.0.0.1:4040/ws').then((socket) { |
| 126 * socket.add('Hello, World!'); |
| 127 * }); |
| 128 * |
| 129 * Check out the |
| 130 * [dartiverse_search](https://code.google.com/p/dart/source/browse/branches/ble
eding_edge/dart/samples/dartiverse_search) |
| 131 * sample for a client/server pair that uses |
| 132 * WebSockets to communicate. |
| 133 * |
| 134 * ## Socket and ServerSocket |
| 135 * |
| 136 * Clients and servers use [Socket]s to communicate using the TCP protocol. |
| 137 * Use [ServerSocket] on the server side and [Socket] on the client. |
| 138 * The server creates a listening socket using the `bind()` method and |
| 139 * then listens for incoming connections on the socket. For example: |
| 140 * |
| 141 * ServerSocket.bind('127.0.0.1', 4041) |
| 142 * .then((serverSocket) { |
| 143 * serverSocket.listen((socket) { |
| 144 * socket.transform(UTF8.decoder).listen(print); |
| 145 * }); |
| 146 * }); |
| 147 * |
| 148 * A client connects a Socket using the `connect()` method, |
| 149 * which returns a Future. |
| 150 * Using `write()`, `writeln()`, or `writeAll()` are the easiest ways to |
| 151 * send data over the socket. |
| 152 * For example: |
| 153 * |
| 154 * Socket.connect('127.0.0.1', 4041).then((socket) { |
| 155 * socket.write('Hello, World!'); |
| 156 * }); |
| 157 * |
| 158 * Besides [Socket] and [ServerSocket], the [RawSocket] and |
| 159 * [RawServerSocket] classes are available for lower-level access |
| 160 * to async socket IO. |
| 161 * |
| 162 * ## Standard output, error, and input streams |
| 163 * |
| 164 * This library provides the standard output, error, and input |
| 165 * streams, named 'stdout', 'stderr', and 'stdin', respectively. |
| 166 * |
| 167 * The stdout and stderr streams are both [IOSink]s and have the same set |
| 168 * of methods and properties. |
| 169 * |
| 170 * To write a string to 'stdout': |
| 171 * |
| 172 * stdout.writeln('Hello, World!'); |
| 173 * |
| 174 * To write a list of objects to 'stderr': |
| 175 * |
| 176 * stderr.writeAll([ 'That ', 'is ', 'an ', 'error.', '\n']); |
| 177 * |
| 178 * The standard input stream is a true [Stream], so it inherits |
| 179 * properties and methods from the Stream class. |
| 180 * |
| 181 * To read text synchronously from the command line |
| 182 * (the program blocks waiting for user to type information): |
| 183 * |
| 184 * String inputText = stdin.readLineSync(); |
| 185 * |
| 186 * ## Other resources |
| 187 * |
| 188 * For an introduction to I/O in Dart, see the |
| 189 * [dart:io section of the library tour] |
| 190 * (https://www.dartlang.org/docs/dart-up-and-running/contents/ch03.html#ch03-da
rtio---file-and-socket-io-for-command-line-apps). |
| 191 * |
| 192 * To learn more about I/O in Dart, refer to the |
| 193 * [tutorial about writing command-line apps] |
| 194 * (https://www.dartlang.org/docs/tutorials/io/). |
14 */ | 195 */ |
15 library dart.io; | 196 library dart.io; |
16 | 197 |
17 import 'dart:async'; | 198 import 'dart:async'; |
18 import 'dart:_collection-dev'; | 199 import 'dart:_collection-dev'; |
19 import 'dart:collection' show HashMap, | 200 import 'dart:collection' show HashMap, |
20 HashSet, | 201 HashSet, |
21 LinkedList, | 202 LinkedList, |
22 LinkedListEntry; | 203 LinkedListEntry; |
23 import 'dart:convert'; | 204 import 'dart:convert'; |
(...skipping 24 matching lines...) Expand all Loading... |
48 part 'platform_impl.dart'; | 229 part 'platform_impl.dart'; |
49 part 'process.dart'; | 230 part 'process.dart'; |
50 part 'socket.dart'; | 231 part 'socket.dart'; |
51 part 'stdio.dart'; | 232 part 'stdio.dart'; |
52 part 'string_transformer.dart'; | 233 part 'string_transformer.dart'; |
53 part 'timer_impl.dart'; | 234 part 'timer_impl.dart'; |
54 part 'secure_socket.dart'; | 235 part 'secure_socket.dart'; |
55 part 'secure_server_socket.dart'; | 236 part 'secure_server_socket.dart'; |
56 part 'websocket.dart'; | 237 part 'websocket.dart'; |
57 part 'websocket_impl.dart'; | 238 part 'websocket_impl.dart'; |
OLD | NEW |