Библиотека dart:io

Поддержка файлов, сокетов, HTTP и других операций ввода-вывода в приложениях, не предназначенных для веба.

Важно: Браузерные приложения не могут использовать эту библиотеку. Импортировать и использовать библиотеку dart:io могут только:

• серверы
• скрипты командной строки
• мобильные приложения Flutter
• настольные приложения Flutter

Эта библиотека позволяет работать с файлами, каталогами, сокетами, процессами, HTTP-серверами и клиентами и многим другим. Многие операции ввода-вывода выполняются асинхронно и обрабатываются с помощью Future или Stream, определённых в библиотеке dart:async.

Чтобы использовать библиотеку dart:io в коде:

import 'dart:io';

Введение в операции ввода-вывода в Dart см. в обзоре библиотеки dart:io.

Файл, каталог и ссылка

Экземпляр File, Directory или Link представляет соответственно файл, каталог или ссылку в собственной файловой системе.

Объекты этих типов позволяют работать с файловой системой. Например, можно переименовать файл или каталог:

File myFile = File('myFile.txt');
myFile.rename('yourFile.txt').then((_) => print('file renamed'));

Многие методы классов File, Directory и Link выполняются асинхронно и возвращают Future.

FileSystemEntity

File, Directory и Link являются подклассами FileSystemEntity. Помимо того, что FileSystemEntity является суперклассом этих классов, он содержит ряд статических методов для работы с путями.

Чтобы получить информацию о пути, можно использовать статические методы FileSystemEntity, например FileSystemEntity.isDirectory, FileSystemEntity.isFile и FileSystemEntity.exists. Поскольку доступ к файловой системе связан с вводом-выводом, эти методы выполняются асинхронно и возвращают Future.

FileSystemEntity.isDirectory(myPath).then((isDir) {
  if (isDir) {
    print('$myPath is a directory');
  } else {
    print('$myPath is not a directory');
  }
});

HttpServer и HttpClient

Классы HttpClient и HttpServer предоставляют низкоуровневые средства для работы с HTTP.

Вместо непосредственного использования этих классов рассмотрите более удобные для разработчиков и комбинируемые API из пакетов.

Для HTTP-клиентов см. пакет package:http.

Инструкции по созданию HTTP-серверов см. в руководстве «Создание HTTP-серверов» на сайте dart.dev.

Процесс

Класс Process позволяет запускать процесс на собственной машине. Например, следующий код запускает процесс, рекурсивно выводящий список файлов в каталоге web.

Process.start('ls', ['-R', 'web']).then((process) {
  stdout.addStream(process.stdout);
  stderr.addStream(process.stderr);
  process.exitCode.then(print);
});

Вызов Process.start возвращает Future, который завершается объектом Process после запуска процесса. Этот объект Process позволяет взаимодействовать с процессом во время его выполнения. Вызов Process.run возвращает Future, который завершается объектом ProcessResult после завершения запущенного процесса. Объект ProcessResult содержит вывод процесса и код завершения.

При использовании Process.start необходимо считывать все данные из потоков Process.stdout и Process.stderr, иначе системные ресурсы не будут освобождены.

WebSocket

Класс WebSocket обеспечивает поддержку протокола веб-сокетов. Он позволяет клиентским и серверным приложениям обмениваться данными в полнодуплексном режиме.

Сервер веб-сокетов использует обычный HTTP-сервер для приёма подключений веб-сокетов. Начальное рукопожатие выполняется с помощью HTTP-запроса, который затем преобразуется в подключение веб-сокета. Сервер преобразует запрос с помощью WebSocketTransformer и прослушивает данные в возвращённом веб-сокете. Например, вот небольшой сервер, который прослушивает данные 'ws' в WebSocket:

runZoned(() async {
  var server = await HttpServer.bind('127.0.0.1', 4040);
  server.listen((HttpRequest req) async {
    if (req.uri.path == '/ws') {
      var socket = await WebSocketTransformer.upgrade(req);
      socket.listen(handleMsg);
    }
  });
}, onError: (e) => print("An error occurred."));

Клиент подключается к WebSocket с помощью метода WebSocket.connect и URI, использующего протокол Web Socket. Клиент может записывать данные в WebSocket с помощью метода WebSocket.add. Например:

var socket = await WebSocket.connect('ws://127.0.0.1:4040/ws');
socket.add('Hello, World!');

Посмотрите приложение websocket_sample, в котором для обмена данными с сервером используются WebSocket.

Socket и ServerSocket

Клиенты и серверы используют Socket для обмена данными по протоколу TCP. На стороне сервера используйте ServerSocket, а на стороне клиента — Socket. Сервер создаёт прослушивающий сокет с помощью метода bind(), а затем ожидает входящие подключения через этот сокет. Например:

ServerSocket.bind('127.0.0.1', 4041)
  .then((serverSocket) {
    serverSocket.listen((socket) {
      socket.transform(utf8.decoder).listen(print);
    });
  });

Клиент подключает Socket с помощью метода connect(), который возвращает Future. Использование write(), writeln() или writeAll() — самые простые способы отправки данных через сокет. Например:

Socket.connect('127.0.0.1', 4041).then((socket) {
  socket.write('Hello, World!');
});

Помимо Socket и ServerSocket, классы RawSocket и RawServerSocket обеспечивают низкоуровневый доступ к асинхронному вводу-выводу через сокеты.

Стандартные потоки вывода, ошибок и ввода

Эта библиотека предоставляет стандартные потоки вывода, ошибок и ввода, называемые соответственно stdout, stderr и stdin.

Потоки stdout и stderr являются объектами IOSink и имеют одинаковый набор методов и свойств.

Чтобы записать строку в stdout:

stdout.writeln('Hello, World!');

Чтобы записать список объектов в stderr:

stderr.writeAll([ 'That ', 'is ', 'an ', 'error.', '\n']);

Стандартный поток ввода является полноценным Stream, поэтому он наследует свойства и методы класса Stream.

Чтобы синхронно прочитать текст из командной строки (программа ожидает, пока пользователь введёт данные):

String? inputText = stdin.readLineSync();

Классы

BytesBuilder

Создаёт список байтов, позволяя добавлять в его конец байты и списки байтов.

CompressionOptions

Параметры сжатия в WebSocket.

ConnectionTask<S>

Отменяемая попытка подключения.

ContentType

Тип носителя MIME/IANA, используемый в качестве значения заголовка HttpHeaders.contentTypeHeader.

Cookie

Представление файла cookie. Для файлов cookie, полученных сервером в виде значений заголовка Cookie, будут заданы только свойства name и value. При формировании файла cookie для заголовка 'set-cookie' на сервере и при получении файлов cookie клиентом в виде заголовков 'set-cookie' можно использовать все поля.

Datagram

Пакет данных, полученный объектом RawDatagramSocket.

Directory

Ссылка на каталог (или папку) в файловой системе.

File

Ссылка на файл в файловой системе.

FileLock

Тип блокировки, запрашиваемой для файла.

FileMode

Режимы, в которых можно открыть File.

FileStat

Результат вызова функции POSIX stat() для объекта файловой системы.

FileSystemCreateEvent

Событие файловой системы о создании новых объектов файловой системы.

FileSystemDeleteEvent

Событие файловой системы об удалении объектов файловой системы.

FileSystemEntity

Общий суперкласс для File, Directory и Link.

FileSystemEntityType

Тип объекта файловой системы, например файл, каталог или ссылка.

FileSystemEvent

Базовый класс событий, генерируемых методом FileSystemEntity.watch.

FileSystemModifyEvent

Событие файловой системы об изменении объектов файловой системы.

FileSystemMoveEvent

Событие файловой системы о перемещении объектов файловой системы.

GZipCodec

GZipCodec кодирует исходные байты в байты, сжатые с помощью GZip, и декодирует сжатые с помощью GZip байты в исходные.

HeaderValue

Представление значения заголовка в формате:

HttpClient

HTTP-клиент для обмена данными с HTTP-сервером.

HttpClientBasicCredentials

Представляет учётные данные для базовой аутентификации.

HttpClientCredentials

HttpClientDigestCredentials

Представляет учётные данные для дайджест-аутентификации. Дайджест-аутентификация поддерживается только на серверах, использующих алгоритм MD5 и уровень защиты (qop) "none" или "auth".

HttpClientRequest

HTTP-запрос для клиентского подключения.

HttpClientResponse

HTTP-ответ для клиентского подключения.

HttpConnectionInfo

Информация о подключении HttpRequest, HttpResponse, HttpClientRequest или HttpClientResponse.

HttpConnectionsInfo

Сводная статистика о текущих сокетных подключениях HttpServer.

HttpDate

Вспомогательные функции для работы с датами в форматах, специфичных для HTTP.

HttpHeaders

Заголовки HTTP-запросов и ответов.

HttpOverrides

Этот класс позволяет подменить HttpClient имитационной реализацией. В клиентском коде его следует расширить другим классом с переопределениями, создающими имитационную реализацию. В этом базовом классе по умолчанию используется настоящая реализация HttpClient. Например:

HttpRequest

Объект на стороне сервера, содержащий содержимое и сведения об HTTP-запросе.

HttpResponse

HTTP-ответ, возвращающий заголовки и данные с сервера клиенту в ответ на HTTP-запрос.

HttpServer

Сервер, доставляющий содержимое, например веб-страницы, по протоколу HTTP.

HttpSession

Объект HttpRequest.session для HttpRequest.

HttpStatus

Коды состояния HTTP. Экспортируется в dart:io и dart:html.

InternetAddress

Интернет-адрес или адрес домена Unix.

InternetAddressType

Тип, или семейство адресов, объекта InternetAddress.

IOOverrides

Средства для подмены различных API dart:io имитационными реализациями.

IOSink

Объединённый поток вывода байтов и текста.

Link

Ссылки на ссылки файловой системы.

NetworkInterface

NetworkInterface представляет активный сетевой интерфейс текущей системы. Он содержит список объектов InternetAddress, привязанных к этому интерфейсу.

Pipe

Анонимный канал для однонаправленной передачи данных: данные, записанные с помощью write, можно прочитать с помощью read.

Platform

Информация об окружении, в котором выполняется текущая программа.

Process

Средство для выполнения программы.

ProcessInfo

Методы для получения информации о текущем процессе.

ProcessResult

Результат выполнения неинтерактивного процесса, запущенного с помощью Process.run или Process.runSync.

ProcessSignal

В системах Posix ProcessSignal используется для отправки определённого сигнала дочернему процессу; см. Process.kill.

ProcessStartMode

Режимы запуска нового процесса.

RandomAccessFile

Произвольный доступ к данным в файле.

RawDatagramSocket

Небуферизованный интерфейс для UDP-сокета.

RawSecureServerSocket

Серверный сокет, предоставляющий поток низкоуровневых объектов RawSecureSocket.

RawSecureSocket

RawSecureSocket обеспечивает защищённое сетевое подключение (SSL или TLS).

RawServerSocket

Прослушивающий сокет.

RawSocket

TCP-подключение.

RawSocketEvent

События для RawSocket.

RawSocketOption

RawSocketOption используется как параметр методов Socket.setRawOption и RawSocket.setRawOption для настройки поведения базового сокета.

RawSynchronousSocket

Низкоуровневый класс для синхронного обмена данными через TCP-сокет.

RawZLibFilter

Класс RawZLibFilter предоставляет низкоуровневый интерфейс к zlib.

ReadPipe

Конец «чтения» объекта Pipe, созданного с помощью Pipe.create.

RedirectInfo

Информация о перенаправлении.

ResourceHandle

Обёртка дескриптора ресурса ОС, позволяющая передавать его через сокет как часть SocketMessage.

SecureServerSocket

Серверный сокет, предоставляющий поток высокоуровневых объектов Socket.

SecureSocket

TCP-сокет, использующий TLS и SSL.

SecurityContext

Объект, содержащий сертификаты, которым следует доверять при установлении защищённого клиентского подключения, а также цепочку сертификатов и закрытый ключ для использования защищённым сервером.

ServerSocket

Прослушивающий сокет.

Socket

TCP-подключение между двумя сокетами.

SocketControlMessage

Управляющее сообщение, входящее в состав SocketMessage, полученного вызовом RawSocket.readMessage.

SocketDirection

SocketDirection используется как параметр методов Socket.close и RawSocket.close для закрытия сокета в указанном направлении или направлениях.

SocketMessage

Сообщение сокета, полученное объектом RawDatagramSocket.

SocketOption

Параметр сокета, задаваемый с помощью Socket.setOption.

Stdin

Стандартный поток ввода процесса.

StdioType

Тип объекта, к которому может быть подключён стандартный поток ввода-вывода.

Stdout

IOSink, подключённый к стандартному потоку вывода или ошибок процесса.

SystemEncoding

Текущая системная кодировка: текущая кодовая страница в Windows и UTF-8 в Linux и Mac.

WebSocket

Объект двусторонней HTTP-связи для клиентских или серверных приложений.

WebSocketStatus

Коды состояния WebSocket, используемые при закрытии подключения WebSocket.

WebSocketTransformer

WebSocketTransformer позволяет преобразовать HttpRequest в подключение WebSocket. Он поддерживает преобразование как одного HttpRequest, так и потока объектов HttpRequest.

WritePipe

Конец «записи» объекта Pipe, созданного с помощью Pipe.create.

X509Certificate

X509Certificate представляет SSL-сертификат и предоставляет доступ к его полям.

ZLibCodec

ZLibCodec кодирует исходные байты в байты, сжатые с помощью ZLib, и декодирует сжатые с помощью ZLib байты в исходные.

ZLibDecoder

ZLibDecoder используется классами ZLibCodec и GZipCodec для распаковки данных.

ZLibEncoder

Кодировщик ZLibEncoder используется классами ZLibCodec и GZipCodec для сжатия данных.

ZLibOption

Предоставляет параметры ZLib для входных данных.

Константы

gzip → const GZipCodec

Экземпляр реализации GZipCodec по умолчанию.

const GZipCodec._default()

systemEncoding → const SystemEncoding

Текущая системная кодировка.

const SystemEncoding()

zlib → const ZLibCodec

Экземпляр реализации ZLibCodec по умолчанию.

const ZLibCodec._default()

Свойства

exitCode ↔ int

чтение / запись

Получает глобальный код завершения виртуальной машины Dart.

pid → int

только для чтения

Возвращает PID текущего процесса.

stderr → Stdout

только для чтения

Стандартный поток вывода ошибок, записанных этой программой.

stdin → Stdin

только для чтения

Стандартный поток ввода данных, считываемых этой программой.

stdout → Stdout

только для чтения

Стандартный поток вывода данных, записываемых этой программой.

Функции

exit(int code) → Never

Немедленно завершает процесс виртуальной машины Dart с указанным кодом завершения.

sleep(Duration duration) → void

Приостанавливает выполнение на время, указанное в duration.

stdioType(dynamic object) → StdioType

Определяет, подключён ли поток к файлу, каналу, терминалу или другому объекту.

Перечисления

HttpClientResponseCompressionState

Перечисление, указывающее состояние сжатия потока байтов объекта HttpClientResponse.

Определения типов

BadCertificateCallback = bool Function(X509Certificate cr, String host, int port)

Исключения / ошибки

CertificateException

Исключение, возникающее на этапе рукопожатия при установлении защищённого сетевого подключения во время поиска или проверки сертификата.

FileSystemException

Исключение, возникающее при сбое файловой операции.

HandshakeException

Исключение, возникающее на этапе рукопожатия при установлении защищённого сетевого подключения.

HttpException

IOException

Базовый класс всех исключений, связанных с вводом-выводом.

OSError

Exception, содержащий сведения об ошибке операционной системы.

PathNotFoundException

Исключение, возникающее при сбое файловой операции из-за отсутствия файла или каталога.

ProcessException

RedirectException

SignalException

SocketException

Исключение, возникающее при сбое операции с сокетом.

StdinException

Исключение, возникающее при выполнении некоторых операций объекта Stdin

StdoutException

Исключение, возникающее при выполнении некоторых операций объекта Stdout

TlsException

Исключение при защищённом сетевом взаимодействии, вызванное сбоем протокола TLS/SSL.

WebSocketException