make-network-process

Основная функция для создания сетевых подключений и сетевых серверов — make-network-process. Она может выполнять обе эти задачи в зависимости от переданных аргументов.

Функция: make-network-process &rest args

Эта функция создаёт сетевое подключение или сервер и возвращает объект процесса, который его представляет. Аргументы args — это список пар «ключ/значение». Пропуск ключа всегда эквивалентен указанию значения nil, за исключением :coding, :filter-multibyte, и :reuseaddr. Вот значимые ключи (ключевые параметры, соответствующие сетевым опциям, перечислены в следующем разделе):

:name name

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

:type type

Укажите тип связи. Значение nil задаёт потоковое подключение (по умолчанию); datagram задаёт подключение дейтаграмм; seqpacket задаёт подключение упорядоченных потоков пакетов. Оба подключения и серверы могут иметь эти типы.

:server server-flag

Если server-flag не равно nil, создаётся сервер. В противном случае создаётся подключение. Для сервера потокового типа server-flag может быть целым числом, которое задаёт длину очереди ожидающих подключений к серверу. Длина очереди по умолчанию равна 5.

:host host

Укажите хост, к которому нужно подключиться. host должен быть именем хоста или интернет-адресом в виде строки или символом local для указания локального хоста. Если вы указываете host для сервера, он должен указывать действительный адрес локального хоста, и только клиенты, подключающиеся к этому адресу, будут приняты. При использовании local, по умолчанию используется IPv4, укажите family ipv6, чтобы переопределить это. Чтобы прослушивать все интерфейсы, укажите адрес ‘"0.0.0.0"’ для IPv4 или ‘"::"’ для IPv6. Обратите внимание, что на некоторых операционных системах прослушивание на ‘"::"’ также будет прослушивать IPv4, поэтому попытка отдельного прослушивания на IPv4 приведёт к ошибкам EADDRINUSE (‘"Адрес уже используется"’).

:service service

service задаёт номер порта для подключения; или, для сервера, номер порта для прослушивания. Он должен быть именем службы, например ‘"https"’, которое преобразуется в номер порта, или целым числом, например ‘443’, или строкой с целым числом, например ‘"443"’, которая напрямую задаёт номер порта. Для сервера он также может быть t, что означает, что система должна выбрать свободный номер порта.

:family family

family задаёт семейство адресов (и протокол) для связи. nil означает автоматическое определение соответствующего семейства адресов для заданных host и service. local задаёт сокет Unix, в этом случае host игнорируется. ipv4 и ipv6 задают использование IPv4 и IPv6 соответственно.

:use-external-socket use-external-socket

Если use-external-socket не равно nil, использовать любые сокеты, переданные в Emacs при вызове, вместо выделения своего. Это используется кодом сервера Emacs для разрешения активации сокетов по требованию. Если Emacs не получил сокет, этот параметр будет проигнорирован.

:local local-address

Для процесса-сервера local-address — это адрес для прослушивания. Он переопределяет family, host и service, поэтому вы можете их не указывать.

:remote remote-address

Для подключения remote-address — это адрес для подключения. Он переопределяет family, host и service, поэтому вы можете их не указывать.

Для сервера дейтаграмм remote-address задаёт начальное значение удалённого адреса дейтаграммы.

Формат local-address или remote-address зависит от семейства адресов:

• - IPv4-адрес представляется как вектор из пяти элементов: четырёх 8-битных целых чисел и одного 16-битного целого числа [a b c d p] соответствующего числовому IPv4-адресу a.b.c.d и номеру порта p.
• - IPv6-адрес представляется как вектор из девяти элементов 16-битных целых чисел [a b c d e f g h p] соответствующего числовому IPv6-адресу a:b:c:d:e:f:g:h и номеру порта p.
• - Локальный адрес представляется как строка, которая задаёт адрес в локальном адресном пространстве.
• - Адрес неподдерживаемого семейства представляется консом (f . av), где f — номер семейства, а av — вектор, определяющий адрес сокета с использованием одного элемента на байт данных адреса. Не полагайтесь на этот формат в переносимом коде, так как он может зависеть от определённых реализацией констант, размеров данных и выравнивания структуры данных.

:nowait bool

Если bool не равно nil для потокового подключения, возвращает без ожидания завершения подключения. Когда подключение удаётся или терпит неудачу, Emacs вызывает функцию сторожевого сигнала, со вторым аргументом, соответствующим "open" (если успешно) или "failed". По умолчанию происходит блокировка, чтобы make-network-process не возвращался, пока подключение не завершится успешно или неудачно.

Если вы настраиваете асинхронное TLS-подключение, вы должны также предоставить параметр :tls-parameters (см. ниже).

В зависимости от возможностей Emacs, насколько асинхронным :nowait является, может отличаться. Три элемента, которые могут (или не могут) выполняться асинхронно, это разрешение доменного имени, настройка сокета и (для TLS-соединений) согласование TLS.

Многие функции, взаимодействующие с объектами процесса (например, process-datagram-address) полагаются на то, что у них есть сокет, прежде чем они могут вернуть полезное значение. Эти функции будут блокироваться, пока сокет не достигнет желаемого состояния. Рекомендуемый способ взаимодействия с асинхронными сокетами — установить сторожевой сигнал на процессе и не пытаться взаимодействовать с ним, прежде чем он не изменит статус на ‘"run"’. Таким образом, ни одна из этих функций не будет блокироваться.

:tls-parameters

При открытии TLS-соединения это должно быть место, где первый элемент — это тип TLS (который должен быть gnutls-x509pki или gnutls-anon, а оставшиеся элементы должны образовывать список ключей, приемлемый для gnutls-boot. (Этот список ключей можно получить из функции gnutls-boot-parameters.) Затем TLS-подключение будет согласовано после завершения подключения к хосту.

:stop stopped

Если stopped не равно nil, начать сетевое подключение или сервер в состоянии остановки.

:buffer buffer

Используйте buffer в качестве буфера процесса.

:coding coding

Используйте coding в качестве кодировки для этого процесса. Чтобы указать разные кодировки для декодирования данных из подключения и кодирования данных, отправляемых в него, укажите (decoding . encoding) для coding.

Если вы не указываете этот ключ, по умолчанию кодировки определяются из данных.

:noquery query-flag

Инициализируйте флаг запроса процесса значением query-flag. См. Запрос перед выходом.

:filter filter

Инициализируйте фильтр процесса значением filter.

:filter-multibyte multibyte

Если multibyte не равно nil, строки, передаваемые в фильтр процесса, являются многобайтовыми, в противном случае — однобайтовыми. По умолчанию t.

:sentinel sentinel

Инициализируйте сторожевой сигнал процесса значением sentinel.

:log log

Инициализируйте функцию логирования процесса-сервера значением log. Функция логирования вызывается каждый раз, когда сервер принимает сетевое подключение от клиента. Аргументы, передаваемые функции логирования, это server, connection и message; где server — процесс-сервер, connection — новый процесс для подключения, а message — строка, описывающая произошедшее событие.

:plist plist

Инициализируйте список свойств процесса значением plist.

Исходный список аргументов, изменённый с фактической информацией о подключении, доступен через функцию process-contact.