41.17.1 make-network-process

创建网络连接与网络服务器的基础函数是 make-network-process。根据传入的参数,它既可以创建连接,也可以创建服务器。

Function: make-network-process &rest args

该函数创建一个网络连接或服务器,并返回代表它的进程对象。参数 args 为一组关键字/参数对。省略某个关键字等价于将其值设为 nil,但 :coding:filter-multibyte:reuseaddr 除外。以下为有效关键字(与网络选项相关的关键字将在下一节列出):

:name name

使用字符串 name 作为进程名称。如有必要会对其进行修改以确保唯一。

:type type

指定通信类型。值为 nil 时表示流连接(默认值);datagram 表示数据报连接;seqpacket 表示有序分组流连接。连接与服务端均可使用这些类型。

:server server-flag

server-flagnil,则创建服务端;否则创建连接。对于流类型服务端,server-flag 可为整数,用于指定服务端待处理连接队列的长度。默认队列长度为 5。

:host host

指定要连接的主机。host 应为字符串形式的主机名或互联网地址,或符号 local 以表示本地主机。若为服务端指定 host,则其必须是本地主机的有效地址,且仅接受连接至该地址的客户端。使用 local 时默认采用 IPv4,可指定 familyipv6 覆盖该行为。若要在所有网卡上监听,IPv4 可指定地址为 ‘"0.0.0.0"’,IPv6 为 ‘"::"’。注意在部分操作系统上,监听 ‘"::"’ 会同时监听 IPv4,此时再单独监听 IPv4 将触发 EADDRINUSE 错误(‘"Address already in use"’)。

:service service

service 指定要连接的端口号;对服务端而言则为监听端口号。其可以是类似 ‘"https"’ 可解析为端口的服务名,或 ‘443’ 这样的整数、‘"443"’ 这样的整数字符串以直接指定端口。对服务端,其也可为 t,表示由系统选择未使用的端口号。

:family family

family 指定通信的地址(及协议)族。nil 表示根据给定的 hostservice 自动判断合适的地址族。local 表示 Unix 套接字,此时 host 会被忽略。ipv4ipv6 分别指定使用 IPv4 与 IPv6。

:use-external-socket use-external-socket

use-external-socketnil,则使用 Emacs 启动时传入的套接字而非自行分配。该选项用于 Emacs 服务端代码以实现按需套接字激活。若 Emacs 未传入套接字,此选项会被静默忽略。

:local local-address

对服务端进程,local-address 为监听地址。该参数会覆盖 familyhostservice,因此无需再指定这些参数。

:remote remote-address

对连接,remote-address 为要连接的目标地址。该参数会覆盖 familyhostservice,因此无需再指定这些参数。

对数据报服务端,remote-address 指定远程数据报地址的初始值。

local-addressremote-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
  • 本地地址以字符串表示,指定本地地址空间中的地址。
  • 不支持的地址族地址以 cons (f . av) 表示,其中 f 为地址族编号,av 为向量,每个元素对应一个地址数据字节以表示套接字地址。可移植代码中不应依赖该格式,因其可能取决于实现定义的常量、数据大小与数据结构对齐方式。
:nowait bool

对流连接,若 boolnil,则无需等待连接完成即返回。当连接成功或失败时,Emacs 会调用标记函数,第二个参数为 "open"(成功)或 "failed"(失败)。默认行为为阻塞,即 make-network-process 会等待连接成功或失败后才返回。

若要建立异步 TLS 连接,还需同时提供 :tls-parameters 参数(见下文)。

根据 Emacs 功能支持情况,:nowait 的异步实现方式可能不同。可异步执行的操作包括域名解析、套接字建立(TLS 连接还包括 TLS 协商)。

许多与进程对象交互的函数(如 process-datagram-address)需要进程至少已创建套接字才能返回有效结果,这些函数会阻塞至套接字达到预期状态。与异步套接字交互的推荐方式是为进程设置标记函数,并在其状态变为 ‘"run"’ 前不进行操作,这样可避免上述函数阻塞。

:tls-parameters

打开 TLS 连接时,该参数首元素应为 TLS 类型(gnutls-x509pkignutls-anon),剩余元素组成可用于 gnutls-boot 的关键字参数列表(该列表可通过 gnutls-boot-parameters 函数获取)。TLS 协商将在与主机建立连接后进行。

:stop stopped

stoppednil,则网络连接或服务端以停止状态启动。

:buffer buffer

使用 buffer 作为进程缓冲区。

:coding coding

使用 coding 作为该进程的编码系统。若要为从连接接收数据的解码与向连接发送数据的编码分别指定不同编码系统,可将 coding 设为 (decoding . encoding)

若未指定该关键字,默认根据数据自动确定编码系统。

:noquery query-flag

将进程查询标志初始化为 query-flag。See 退出前询问确认

:filter filter

将进程过滤器初始化为 filter

:filter-multibyte multibyte

multibytenil,传递给进程过滤器的字符串为多字节编码,否则为单字节。默认值为 t

:sentinel sentinel

将进程标记函数初始化为 sentinel

:log log

将服务端进程的日志函数初始化为 log。每次服务端接受客户端网络连接时都会调用该日志函数,传入参数为 serverconnectionmessage;其中 server 为服务端进程,connection 为对应连接的新进程,message 为描述事件的字符串。

:plist plist

将进程属性列表初始化为 plist

可通过 process-contact 函数获取已填入实际连接信息的原始参数列表。