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

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

Важно: Приложения, работающие в браузере, не могут использовать эту библиотеку. Только следующие могут импортировать и использовать библиотеку dart:io:

• Серверы
• Сценарии командной строки
• Мобильные приложения Flutter
• Приложения Flutter для настольных компьютеров

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

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

import 'dart:io';

Для введения в I/O в 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 предоставляет поддержку протокола WebSocket. Это позволяет реализовать двустороннюю связь между клиентскими и серверными приложениями.

Сервер WebSocket использует обычный HTTP-сервер для приема подключений WebSocket. Первоначальный обмен данными — это HTTP-запрос, который затем повышается до подключения WebSocket. Сервер повышает запрос с помощью WebSocketTransformer и слушает данные возвращённого WebSocket. Например, вот мини-сервер, который слушает данные '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, использующего протокол WebSocket. Клиент может писать в WebSocket с помощью метода WebSocket.add. Например,

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

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

Сокет и 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, будут установлены только свойства name и value. При создании куки для заголовка 'set-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

Представляет данные для аутентификации по принципу basic.

HttpClientCredentials

HttpClientDigestCredentials

Представляет данные для аутентификации по принципу digest. Аутентификация по принципу digest поддерживается только для серверов, использующих алгоритм 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е, привязанных к интерфейсу.

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.

RedirectInfo

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

ResourceHandle

Обёртка над системным ресурсом, так что он может быть передан через Socket в качестве части SocketMessage.

SecureServerSocket

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

SecureSocket

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

SecurityContext

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

ServerSocket

Слушающий сокет.

Socket

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

SocketControlMessage

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

SocketDirection

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

СообщениеСокета

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

ПараметрСокета

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

СтандартныйВвод

Поток стандартного ввода процесса.

ТипStdio

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

СтандартныйВывод

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

КодировкаСистемы

Кодировка системы — текущая кодовая страница в Windows и UTF-8 в Linux и macOS.

WebSocket

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

СтатусWebSocket

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

ПреобразовательWebSocket

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

X509Сертификат

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

ZLibКодек

ZLibКодек кодирует сырые байты в сжатые байты ZLib и декодирует сжатые байты ZLib в сырые байты.

ZLibДекодер

ZLibДекодер используется ZLibКодек и GZipКодек для распаковки данных.

ZLibКодировщик

Кодировщик ZLibКодировщик используется ZLibКодек и GZipКодек для сжатия данных.

ПараметрZLib

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

Константы

gzip → const GZipCodec

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

const GZipCodec._default()

systemEncoding → const КодировкаСистемы

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

const SystemEncoding()

zlib → const ZLibКодек

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

const ZLibCodec._default()

Свойства

exitCode ↔ int

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

Получить глобальный код выхода для Dart VM.

pid → int

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

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

stderr → СтандартныйВывод

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

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

stdin → СтандартныйВвод

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

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

stdout → СтандартныйВывод

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

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

Функции

exit(int code) → Never

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

sleep(Duration duration) → void

Отложить выполнение на заданную продолжительность duration.

stdioType(dynamic object) → ТипStdio

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

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

СостояниеСжатияОткликаHttpClient

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

Типы

ОбратныйВызовНеверногоСертификата = bool Function(X509Сертификат cr, String host, int port)

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

ИсключениеСертификата

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

ИсключениеФайловойСистемы

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

ИсключениеРукопожатия

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

ИсключениеHttp

ИсключениеВводаВывода

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

ОшибкаОС

Исключение, содержащее информацию об ошибке операционной системы.

ИсключениеПроцесса

ИсключениеПеренаправления

ИсключениеСигнала

ИсключениеСокета

Исключение, выбрасываемое, когда операция сокета терпит неудачу.

ИсключениеСтандартногоВвода

Исключение, выбрасываемое некоторыми операциями СтандартныйВвод

ИсключениеСтандартногоВывода

Исключение, выбрасываемое некоторыми операциями СтандартныйВывод

ИсключениеTls

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

ИсключениеWebSocket