socket 包

介绍

用于进行网络通信，提供启动 Socket 服务器、连接 Socket 服务器、发送数据、接收数据等功能。我们支持 UDP/TCP/UDS 三种 Socket 类型，用户可按需选用。

如下为本库提供 Socket 的类继承关系：

Hierarchy
 Resource
 ├StreamingSocket
 │   ├TcpSocket
 │   └UnixSocket
 │
 ├DatagramSocket
 │   ├UdpSocket
 │   └UnixDatagramSocket
 │
 └ServerSocket
    ├TcpServerSocket
    └UnixServerSocket

主要接口

IPV6_INTERFACE_LOCAL_ALL_NODES

public let IPV6_INTERFACE_LOCAL_ALL_NODES: Array<UInt8>

功能：IPv6 在节点本地范围的所有节点多播地址。

interface StreamingSocket

public interface StreamingSocket <: IOStream & Resource & ToString {
    prop localAddress: SocketAddress
    prop remoteAddress: SocketAddress
    mut prop readTimeout: ?Duration
    mut prop writeTimeout: ?Duration
}

双工流模式下的运行的 Socket，可被读写。 StreamingSocket 可以被绑定 (bind) 和连接 (connect), 用户可以通过属性设置绑定和连接的远端和本地地址。 StreamingSocket 可以有序分包传输字节流。我们会使用一段缓存空间存储读写的字节流。读取接口 (read()) 默认在无数据到来时阻塞式等待，直到下一次数据到达，或超时。写操作 (write()) 会写入缓存中的数据并在后续被发出，如果缓存不足，或者写入速度快于转发速度，写操作将会阻塞等待缓存空闲，或超时。读写字符始终保持有序, 但不保证传输过程中的分包策略及大小与发包时一致。例如：一端发送 10 字节报文后，又发送了 15 字节报文，对端可能分别收到 10 字节和 15 字节报文，也可能一次性收到 25 字节的一个报文。当收到一段异常报文时，将返回报文长度为 -1 。

prop localAddress

prop localAddress: SocketAddress

功能：Socket 将要或已经被绑定的本地地址

异常：

SocketException：当 Socket 已经被关闭或无可用的本地地址（本地地址未配置并且套接字未连接）时抛出异常

prop remoteAddress

prop remoteAddress: SocketAddress

功能：Socket 将要或已经连接的远端地址。

异常：

SocketException：当 Socket 已经被关闭时抛出异常

prop readTimeout

mut prop readTimeout: ?Duration

功能：设置和读取读超时时间。

返回值：超时时间或 None，如果设置的时间过小将会设置为最小时钟周期值；过大时将设置为最大超时时间（(2⁶³-1) 纳秒）；默认值为 None

异常：

IllegalArgumentException：当超时时间小于 0 时，抛出异常

prop writeTimeout

mut prop writeTimeout: ?Duration

功能：设置和读取写超时时间。

返回值：超时时间或 None，如果设置的时间过小将会设置为最小时钟周期值；过大时将设置为最大超时时间（(2⁶³-1) 纳秒）；默认值为 None

异常：

IllegalArgumentException：当超时时间小于 0 时，抛出异常

interface DatagramSocket

public interface DatagramSocket <: Resource & ToString {
    prop localAddress: SocketAddress
    prop remoteAddress: ?SocketAddress
    mut prop receiveTimeout: ?Duration
    mut prop sendTimeout: ?Duration
    func receiveFrom(buffer: Array<Byte>): (SocketAddress, Int64)
    func sendTo(address: SocketAddress, payload: Array<Byte>): Unit
}

DatagramSocket 是一种接受和读取数据包的套接字，一个数据包通常有有限的大小，可能为空。不同的数据包套接字类型有不同的数据包最大值。例如 UDP 套接字一次可以处理最大 64KB 的数据包。

数据包传输不是一种可靠的传输，不保证传输顺序。数据包大小在发送端决定，例如：一端发送了 10 字节和 15 字节的报文，对端将收到相同大小的对应报文，10 字节和 15 字节。

prop localAddress

prop localAddress: SocketAddress

功能：Socket 将要或已经被绑定的本地地址。

异常：

SocketException：当 Socket 已经被关闭或无可用的本地地址（本地地址未配置并且套接字未连接）时抛出异常

prop remoteAddress

prop remoteAddress: ?SocketAddress

功能：Socket 已经连接的远端地址，当 Socket 未连接时返回 None。

异常：

SocketException：当 Socket 已经被关闭时抛出异常

prop receiveTimeout

mut prop receiveTimeout: ?Duration

功能：设置和读取 receiveFrom 超时时间, 无超时时间设置为 None。

返回值：超时时间或 None，如果设置的时间过小将会设置为最小时钟周期值；过大时将设置为最大超时时间（2⁶³-1 纳秒）；默认值为 None

异常：

IllegalArgumentException：当超时时间小于 0 时，抛出异常

prop sendTimeout

mut prop sendTimeout: ?Duration

功能：设置和读取 sendTo 超时时间, 默认设置为 None。

返回值：超时时间或 None，如果设置的时间过小将会设置为最小时钟周期值；过大时将设置为最大超时时间（(2⁶³-1) 纳秒）；默认值为 None

异常：

IllegalArgumentException：当超时时间小于 0 时，抛出异常

func receiveFrom

func receiveFrom(buffer: Array<Byte>): (SocketAddress, Int64)

功能：阻塞式等待收取报文到 buffer 中。

参数：

buffer：存储报文内容的缓存空间，buffer 应当有一个合适的大小，否则可能导致收取报文时报文被截断，并且返回的报文大小值大于 buffer 的大小

返回值：报文发送地址和收取到的报文大小（可能为 0，或大于参数 buffer 大小）。

异常：

SocketException：本机缓存过小无法读取报文时，抛出异常
SocketTimeoutException：读取超时时抛出异常

func sendTo

func sendTo(address: SocketAddress, payload: Array<Byte>): Unit

功能：发送报文到指定的远端地址，当对端无足够缓存时此操作可能被阻塞，报文可能被丢弃。

参数：

address：需要发送的远端地址
payload：需要发送的报文内容

interface ServerSocket

public interface ServerSocket <: Resource & ToString {
    prop localAddress: SocketAddress
    func bind(): Unit
    func accept(timeout!: ?Duration): StreamingSocket
    func accept(): StreamingSocket
}

prop localAddress

prop localAddress: SocketAddress

功能：Socket 将要或已经被绑定的本地地址。

异常：

SocketException：当 Socket 已经被关闭时抛出异常

func bind

func bind(): Unit

功能：绑定套接字，当没有设置 reuse 属性，本地端口、地址、文件路径已被占用时，或还有上次绑定套接字的连接将绑定失败失败后需要 close 套接字，不支持多次重试此操作后可执行 accept() 操作。

异常：

SocketException：当因系统原因绑定失败时抛出异常

func accept

func accept(timeout!: ?Duration): StreamingSocket

功能：接受一个客户端套接字的连接请求，阻塞式等待连接请求。

参数：

timeout：等待连接超时的时间

返回值：连接成功的客户端套接字

异常：

SocketTimeoutException：等待连接请求超时
IllegalArgumentException：当超时时间小于 0 时，抛出异常

func accept

func accept(): StreamingSocket

功能：接受一个客户端套接字的连接请求，阻塞式等待连接请求。

返回值：连接成功的客户端套接字

class TcpSocket

public class TcpSocket <: StreamingSocket & Equatable<TcpSocket> & Hashable {
    public init(address: String, port: UInt16)
    public init(address: SocketAddress)
    public init(address: SocketAddress, localAddress!: ?SocketAddress)
}

TCP 套接字，当实例对象被创建后，可使用 connect 函数创建连接，并在结束时显式执行 close 操作。该类型继承自 StreamingSocket，可参阅 StreamingSocket 章节获取更多信息。

init

public init(address: String, port: UInt16)

功能：创建一个未连接的套接字。

参数：

address：即将要连接的地址，当前仅支持 IPv4 地址
port：即将要连接的端口。

异常：

SocketException：当 address 参数不合法时抛出异常，规格同 SocketAddress 实例创建时的要求
SocketException：Windows 平台下地址为全零地址时将抛出异常

init

public init(address: SocketAddress)

功能：创建一个未连接的套接字。

参数：

address：即将要连接的地址，当前仅支持 IPv4 地址

异常：

SocketException：当 address 参数不合法时抛出异常，规格同 SocketAddress 实例创建时的要求
SocketException：Windows 平台下地址为全零地址时将抛出异常

init

public init(address: SocketAddress, localAddress!: ?SocketAddress)

功能：创建一个未连接的套接字，并且绑定到指定本地地址，本地地址为 None 时，将随机选定地址去绑定。此接口当 localAddress 不为 None 时，将默认设置 SO_REUSEADDR 为 true，否则可能导致 "address already in use" 的错误。如果需要变更此配置，可以通过调用 setSocketOptionBool(SocketOptions.SOL_SOCKET, SocketOptions.SO_REUSEADDR, false)。另外，本地地址和远端地址需要均为 IPv4。

参数：

address：即将要连接的地址
localAddress：绑定的本地地址

异常：

SocketException：当 address 参数不合法时抛出异常，规格同 SocketAddress 实例创建时的要求
SocketException：Windows 平台下地址为全零地址时将抛出异常

prop remoteAddress

public override prop remoteAddress: SocketAddress

功能：Socket 已经或将要连接的远端地址。

异常：

SocketException：当 Socket 已经被关闭时抛出异常

prop localAddress

public override prop localAddress: SocketAddress

功能：Socket 将要或已经被绑定的本地地址。

异常：

SocketException：当 Socket 已经被关闭或无可用的本地地址（本地地址未配置并且套接字未连接）时抛出异常

prop bindToDevice

public mut prop bindToDevice: ?String

功能：设置和读取绑定网卡。

prop readTimeout

public override mut prop readTimeout: ?Duration

功能：设置和读取读操作超时时间。

返回值：超时时间或 None，如果设置的时间过小将会设置为最小时钟周期值；过大时将设置为最大超时时间（(2⁶³-1) 纳秒）；默认值为 None

异常：

IllegalArgumentException：当超时时间小于 0 时，抛出异常

prop writeTimeout

public override mut prop writeTimeout: ?Duration

功能：设置和读取写操作超时时间。

返回值：超时时间或 None，如果设置的时间过小将会设置为最小时钟周期值；过大时将设置为最大超时时间（(2⁶³-1) 纳秒）；默认值为 None

异常：

IllegalArgumentException：当超时时间小于 0 时，抛出异常

prop keepAlive

public mut prop keepAlive: ?SocketKeepAliveConfig

功能：设置和读取保活属性，None 表示关闭保活。用户未设置时将使用系统默认配置。设置此配置可能会被延迟或被系统忽略，取决于系统的处理能力。

prop noDelay

public mut prop noDelay: Bool

功能：设置和读取 TCP_NODELAY 属性，默认为 true。这个选项将禁用 Nagel 算法，所有写入字节被无延迟得转发。当属性设置为 false 时，Nagel 算法将在发包前引入延时时间

prop quickAcknowledge

public mut prop quickAcknowledge: Bool

功能：设置和读取 TCP_QUICKACK 属性，默认为 false。这个选项类似于 noDelay，但仅影响 TCP ACK 和第一次响应。不支持 Windows 和 macOS 系统。

prop linger

public mut prop linger: ?Duration

功能：设置和读取 SO_LINGER 属性，默认值取决于系统，None 表示禁用此选项。

如果 SO_LINGER 被设置为 Some(v)，当套接字关闭时，如果还有等待的字节流，我们将在关闭连接前等待 v 时间，如果超过时间，字节流还未被发送，连接将会被异常终止（通过 RST 报文关闭）。
如果 SO_LINGER 被设置为 None，当套接字关闭时，连接将被立即关闭，如果当前等待发送的字符，使用 FIN-ACK 关闭连接, 当还有剩余待发送的字符时，使用 RST 关闭连接。

异常：

IllegalArgumentException：当超时时间小于 0 时，抛出异常

prop sendBufferSize

public mut prop sendBufferSize: Int64

功能：设置和读取 SO_SNDBUF 属性，提供一种方式指定发包缓存大小。选项的生效情况取决于系统。

异常：

IllegalArgumentException：当 size 小于等于 0 时，抛出异常
SocketException：当 Socket 已关闭时，抛出异常

prop receiveBufferSize

public mut prop receiveBufferSize: Int64

功能：设置和读取 SO_RCVBUF 属性，提供一种方式指定收包缓存大小。选项的生效情况取决于系统。

异常：

IllegalArgumentException：当 size 小于等于 0 时，抛出异常
SocketException：当 Socket 已关闭时，抛出异常

func read

public override func read(buffer: Array<Byte>): Int64

功能：读取报文。超时情况按 readTimeout 决定, 详见 readTimeout。

参数：

buffer：读取的数据存储变量

返回值：读取的数据长度

异常：

SocketException：当 buffer 大小为 0 时抛出异常，当因系统原因读取失败时，抛出异常

注：由于系统底层接口差异，如果连接被对端关闭，read 和 write 接口的行为也有相应的差异

Windows 系统上，对端关闭连接后，如果本端调用一次 write，会导致清空缓冲区内容，在此基础上再调用 read 会抛出连接关闭异常
Linux\macOS 系统上，对端关闭连接后，先调用 write 再调用 read 函数仍会读出缓冲区中的内容

func write

public override func write(payload: Array<Byte>): Unit

功能：读取写入。超时情况按 writeTimeout 决定, 详见 writeTimeout。

参数：

payload：写入的数据存储变量

异常：

SocketException：当 buffer 大小为 0 时抛出异常，当因系统原因写入失败时，抛出异常

func connect

public func connect(timeout!: ?Duration = None): Unit

功能：连接远端套接字, 会自动绑定本地地址，因此不需要进行额外的绑定操作。

参数：

timeout：连接超时时间，None 表示无超时时间，并且连接操作无重试，当服务端拒绝连接时，将返回连接失败。并且此操作包含了绑定操作，因此无需重复调用 bind 接口

异常：

IllegalArgumentException：当远端地址不合法时抛出异常
IllegalArgumentException：当连接超时时间小于 0 时，抛出异常
SocketException：当连接因系统原因（例如：套接字已关闭，没有访问权限，系统错误等）无法建立时抛出异常。再次调用可能成功
SocketTimeoutException：当连接超时时抛出异常
IllegalArgumentException：当超时时间小于 0 时，抛出异常

func getSocketOption

public func getSocketOption(
    level: Int32,
    option: Int32,
    value: CPointer<Unit>,
    valueLength: CPointer<UIntNative>
): Unit

功能：读取指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE
value：参数值
valueLength：参数值长度

异常：

SocketException：当 getsockopt 返回失败时抛出异常

func setSocketOption

public func setSocketOption(
    level: Int32,
    option: Int32,
    value: CPointer<Unit>,
    valueLength: UIntNative
): Unit

功能：设置指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE
value：参数值
valueLength：参数值长度

异常：

SocketException：当 setsockopt 返回失败时抛出异常

func getSocketOptionIntNative

public func getSocketOptionIntNative(
    level: Int32,
    option: Int32
): IntNative

功能：读取指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE

返回值：参数值

异常：

SocketException：当 getsockopt 返回失败时或参数大小超过 IntNative 的阈值时抛出异常

func setSocketOptionIntNative

public func setSocketOptionIntNative(
    level: Int32,
    option: Int32,
    value: IntNative
): Unit

功能：设置指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE
value：参数值

异常：

SocketException：当 setsockopt 返回失败时抛出异常。

func getSocketOptionBool

public func getSocketOptionBool(
    level: Int32,
    option: Int32
): Bool

功能：读取指定的套接字参数。从 IntNative 强转而来。0 => false，非 0 => true。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE

返回值：读取到的参数值

异常：

SocketException：当 getsockopt 返回失败时或参数大小超过 IntNative 的阈值时抛出异常。

func setSocketOptionBool

public func setSocketOptionBool(
    level: Int32,
    option: Int32,
    value: Bool
): Unit

功能：设置指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE
value：参数值

异常：

SocketException：当 setsockopt 返回失败时抛出异常

func close

public func close(): Unit

功能：关闭套接字，所有操作除了 close/isClosed 之外，均不允许再调用。接口允许多次调用。

func isClosed

public func isClosed(): Bool

功能：判断套接字是否通过调用 close 显式关闭。

返回值：返回套接字是否已经调用 close 显式关闭。是则返回 true；否则返回 false

operator func ==

public override operator func ==(other: TcpSocket): Bool

功能：判断两个 TcpSocket 实例是否相等。

参数：

other：参与比较的 TcpSocket 实例。

返回值：如果相等，则返回 true；否则，返回 false

operator func !=

public override operator func !=(other: TcpSocket): Bool

功能：判断两个 TcpSocket 实例是否不等。

参数：

other：参与比较的 TcpSocket 实例。

返回值：如果不等，则返回 true；否则，返回 false

func hashCode

public override func hashCode(): Int64

功能：获取当前 TcpSocket 实例的哈希值。

返回值：返回当前 TcpSocket 实例的哈希值

func toString

public override func toString(): String

功能：返回当前 TcpSocket 的状态信息。

返回值：包含当前 TcpSocket 状态信息的字符串。

class TcpServerSocket

public class TcpServerSocket <: ServerSocket {
    public init(bindAt!: UInt16)
    public init(bindAt!: SocketAddress)
}

TcpServerSocket 将监听 TCP 连接。套接字被创建后，可通过属性和 setSocketOptionXX 接口配置属性。启动监听需要调用 bind() 将套接字绑定到本地端口。accept() 接口将接受 TCP 连接，阻塞等待连接，若队列中已有连接，则可立即返回。套接字需要通过 close 显式关闭。当前仅支持 IPv4 协议。

init

public init(bindAt!: UInt16)

功能：创建一个 TcpServerSocket 对象，尚未绑定，因此客户端无法连接。

参数：

bindAt：指定本地绑定端口，0 表示随机绑定空闲的本地端口

init

public init(bindAt!: SocketAddress)

功能：创建一个 TcpServerSocket 对象，尚未绑定，因此客户端无法连接。

参数：

bindAt：指定本地绑定地址，0 表示随机绑定空闲的本地地址

prop localAddress

public override prop localAddress: SocketAddress

功能：Socket 将要或已经被绑定的本地地址。

异常：

SocketException：当 Socket 已经被关闭时抛出异常

prop reuseAddress

public mut prop reuseAddress: Bool

功能：设置和读取 SO_REUSEADDR 属性，默认设置为 true。属性生效后的行为取决于系统，使用前，请参阅不同系统针对此属性 SO_REUSEADDR/SOCK_REUSEADDR 的说明文档。

prop reusePort

public mut prop reusePort: Bool

功能：设置和读取 SO_REUSEPORT 属性。仅可在绑定前被修改。Windows 上可使用 SO_REUSEADDR，无该属性，抛出异常。属性默认及配置生效后的行为取决于系统，使用前，请参阅不同系统针对此属性 SO_REUSEPORT 的说明文档。同时开启 SO_REUSEADDR/SO_REUSEPORT 会导致不可预知的系统错误，用户需谨慎配置次值。

异常：

SocketException： Windows 上不支持此类型，抛出异常

prop sendBufferSize

public mut prop sendBufferSize: Int64

功能：设置和读取 SO_SNDBUF 属性。

异常：

IllegalArgumentException：当 size 小于等于 0 时，抛出异常
SocketException：当 Socket 已关闭时，抛出异常

prop receiveBufferSize

public mut prop receiveBufferSize: Int64

功能：设置和读取 SO_RCVBUF 属性。

异常：

IllegalArgumentException：当 size 小于等于 0 时，抛出异常
SocketException：当 Socket 已关闭时，抛出异常

prop bindToDevice

public mut prop bindToDevice: ?String

功能：设置和读取绑定网卡。

prop backlogSize

public mut prop backlogSize: Int64

功能：设置和读取 backlog 大小。仅可在调用 bind 前调用，否则将抛出异常。变量是否生效取决于系统行为，可能不可预知得被忽略。

异常：

SocketException：当在 bind 后调用，将抛出异常

func bind

public override func bind(): Unit

功能：绑定本地端口失败后需要 close 套接字，不支持多次重试。

异常：

SocketException：当因系统原因绑定失败时抛出异常

func accept

public override func accept(timeout!: ?Duration): TcpSocket

功能：监听或接受客户端连接。

参数：

timeout：超时时间

返回值：客户端套接字

异常：

SocketTimeoutException：连接超时
SocketException：当因系统原因监听失败时抛出异常
IllegalArgumentException：当超时时间小于 0 时，抛出异常

func accept

public override func accept(): TcpSocket

功能：监听或接受客户端连接。阻塞等待。

返回值：客户端套接字

异常：

SocketException：当因系统原因监听失败时抛出异常

func close

public override func close(): Unit

功能：关闭套接字。接口允许多次调用。

func isClosed

public override func isClosed(): Bool

功能：检查套接字是否关闭。

返回值：如果已经关闭，返回 true，否则返回 false。

func getSocketOption

public func getSocketOption(
    level: Int32,
    option: Int32,
    value: CPointer<Unit>,
    valueLength: CPointer<UIntNative>
): Unit

功能：获取指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE
value：参数值
valueLength：参数值长度

异常：

SocketException：当 getsockopt 返回失败时抛出异常

func setSocketOption

public func setSocketOption(
    level: Int32,
    option: Int32,
    value: CPointer<Unit>,
    valueLength: UIntNative
): Unit

功能：设置指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE
value：参数值
valueLength：参数值长度

异常：

SocketException：当 setsockopt 返回失败时抛出异常

func getSocketOptionIntNative

public func getSocketOptionIntNative(
    level: Int32,
    option: Int32
): IntNative

功能：获取指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE

返回值：获取的套接字参数值

异常：

SocketException：当 getsockopt 返回失败时或参数大小超过 IntNative 的阈值时抛出异常。

func setSocketOptionIntNative

public func setSocketOptionIntNative(
    level: Int32,
    option: Int32,
    value: IntNative
): Unit

功能：设置指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE
value：参数值

异常：

SocketException：当 setsockopt 返回失败时抛出异常

func getSocketOptionBool

public func getSocketOptionBool(
    level: Int32,
    option: Int32
): Bool

功能：获取指定的套接字参数。从 IntNative 强转而来。0 => false, 非 0 => true。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE

返回值：返回指定的套接字参数。从 IntNative 强转而来。0 => false, 非 0 => true

异常：

SocketException：当 getsockopt 返回失败时或参数大小超过 IntNative 的阈值时抛出异常

func setSocketOptionBool

public func setSocketOptionBool(
    level: Int32,
    option: Int32,
    value: Bool
): Unit

功能：设置指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE
value：参数值

异常：

SocketException：当 setsockopt 返回失败时抛出异常。

func toString

public override func toString(): String

功能：返回当前 TcpServerSocket 的状态信息。

返回值：包含当前 TcpServerSocket 状态信息的字符串。

class UdpSocket

public class UdpSocket <: DatagramSocket {
    public init(bindAt!: UInt16)
    public init(bindAt!: SocketAddress)
}

UDPSocket 创建实例后，需要调用 bind() 绑定，可在不与远端建连的前提下接受报文。不过，UDPSocket 也可以通过 connect()/disconnect() 接口进行建连。 UDP 协议要求传输报文大小不可超过 64KB 。 UDPSocket 需要被显式 close() 。可以参阅 DatagramSocket 获取更多信息。

init

public init(bindAt!: UInt16)

功能：创建一个未绑定的 UDPSocket。

参数：

bindAt：绑定端口

init

public init(bindAt!: SocketAddress)

功能：创建一个未绑定的 UDPSocket。

参数：

bindAt：绑定地址及端口

prop remoteAddress

public override prop remoteAddress: ?SocketAddress

功能：Socket 已经连接的远端地址，当 Socket 未连接时返回 None。

异常：

SocketException：当 Socket 已经被关闭时抛出异常

prop localAddress

public override prop localAddress: SocketAddress

功能：Socket 将要或已经被绑定的本地地址。

异常：

SocketException：当 Socket 已经被关闭或无可用的本地地址（本地地址未配置并且套接字未连接）时抛出异常

prop receiveTimeout

public override mut prop receiveTimeout: ?Duration

功能：设置和读取 receive/receiveFrom 操作超时时间。

返回值：超时时间或 None，如果设置的时间过小将会设置为最小时钟周期值；过大时将设置为最大超时时间（(2⁶³-1) 纳秒）；默认值为 None

异常：

IllegalArgumentException：当超时时间小于 0 时，抛出异常

prop sendTimeout

public override mut prop sendTimeout: ?Duration

功能：设置和读取 send/sendTo 操作超时时间。

返回值：超时时间或 None，如果设置的时间过小将会设置为最小时钟周期值；过大时将设置为最大超时时间（(2⁶³-1) 纳秒）；默认值为 None

异常：

IllegalArgumentException：当超时时间小于 0 时，抛出异常

func close

public override func close(): Unit

功能：关闭套接字，所有操作除了 close/isClosed 之外，均不允许再调用。接口允许多次调用。

func isClosed

public override func isClosed(): Bool

功能：判断套接字是否通过调用 close 显式关闭。

返回值：如果该套接字已调用 close 显示关闭，则返回 true；否则，返回 false。

func bind

public func bind()

功能：绑定本地端口失败后需要 close 套接字，不支持多次重试。

异常：

SocketException：当因系统原因绑定失败时抛出异常

func connect

public func connect(remote: SocketAddress): Unit

功能：连接特定远端地址，可通过 disconnect 撤销配置。仅接受该远端地址的报文。必须在调用 bind 后执行。此操作执行后，端口将开始接收 ICMP 报文，若收到异常报文后，可能导致 send/sendTo 执行失败。

参数：

remote：远端地址，需要与本地地址都在 IPv4 协议下

异常：

IllegalArgumentException：当远端地址不合法时抛出异常
SocketException：当端口未绑定时抛出异常
SocketException：当连接因系统原因无法建立时抛出异常
SocketException：Windows 平台下远端地址为全零地址时, 将抛出异常

func disconnect

public func disconnect(): Unit

功能：停止连接。取消仅收取特定对端报文。可在 connect 前调用，可多次调用。

func receiveFrom

public override func receiveFrom(buffer: Array<Byte>): (SocketAddress, Int64)

功能：收取报文。

参数：

buffer：存储收取到报文的缓存地址

返回值：收取到的报文的发送端地址，及实际收取到的报文大小，可能为 0 或者大于参数 buffer 的大小

异常：

SocketException：本机缓存过小无法读取报文时，抛出异常
SocketTimeoutException：读取超时时抛出异常

func sendTo

public override func sendTo(recipient: SocketAddress, payload: Array<Byte>): Unit

功能：发送报文。当没有足够的缓存地址时可能会被阻塞。

参数：

recipient：发送的对端地址
payload：发送报文内容

异常：

SocketException：当 payload 的大小超出系统限制
SocketException：系统发送失败，例如：当 connect 被调用，并且收到异常 ICMP 报文时，发送将失败
SocketException：Windows 平台下远端地址为全零地址时, 将抛出异常
SocketException：macOS 平台下当 connect 被调用后调用 sendTo, 将抛出异常

func send

public func send(payload: Array<Byte>): Unit

功能：发送报文到 connect 连接到的地址。

参数：

payload：发送报文内容

异常：

SocketException：当 payload 的大小超出系统限制
SocketException：系统发送失败，例如：当 connect 被调用，并且收到异常 ICMP 报文时，发送将失败

func receive

public func receive(buffer: Array<Byte>): Int64

功能：从 connect 连接到的地址收取报文。

参数：

payload：存储收取到的报文的地址

返回值：收取到的报文大小

prop reusePort

public mut prop reusePort: Bool

功能：设置和读取 SO_REUSEPORT 属性。Windows 上可使用 SO_REUSEADDR，但无 SO_REUSEPORT 属性，因此会抛出异常。属性默认以及配置生效后的行为取决于系统，使用前，请参阅不同系统针对此属性 SO_REUSEPORT 的说明文档。

异常：

SocketException：Windows 上不支持此类型，抛出异常

prop reuseAddress

public mut prop reuseAddress: Bool

功能：设置和读取 SO_REUSEADDR 属性属性默认以及生效后的行为取决于系统，使用前，请参阅不同系统针对此属性 SO_REUSEADDR/SOCK_REUSEADDR 的说明文档。

prop sendBufferSize

public mut prop sendBufferSize: Int64

功能：设置和读取 SO_SNDBUF 属性。

异常：

IllegalArgumentException：当 size 小于等于 0 时，抛出异常
SocketException：当 Socket 已关闭时，抛出异常

prop receiveBufferSize

public mut prop receiveBufferSize: Int64

功能：设置和读取 SO_RCVBUF 属性。

异常：

IllegalArgumentException：当 size 小于等于 0 时，抛出异常
SocketException：当 Socket 已关闭时，抛出异常

func getSocketOption

public func getSocketOption(
    level: Int32,
    option: Int32,
    value: CPointer<Unit>,
    valueLength: CPointer<UIntNative>
): Unit

功能：获取指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE
value：参数值
valueLength：参数值长度

异常：

SocketException：当 getsockopt 返回失败时抛出异常

func setSocketOption

public func setSocketOption(
    level: Int32,
    option: Int32,
    value: CPointer<Unit>,
    valueLength: UIntNative
): Unit

功能：设置指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE
value：参数值
valueLength：参数值长度

异常：

SocketException：当 setsockopt 返回失败时抛出异常

func getSocketOptionIntNative

public func getSocketOptionIntNative(
    level: Int32,
    option: Int32
): IntNative

功能：获取指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE

返回值：指定的套接字参数值

异常：

SocketException：当 getsockopt 返回失败时或参数大小超过 IntNative 的阈值时抛出异常

func setSocketOptionIntNative

public func setSocketOptionIntNative(
    level: Int32,
    option: Int32,
    value: IntNative
): Unit

功能：设置指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE
value：参数值

异常：

SocketException：当 setsockopt 返回失败时抛出异常

func getSocketOptionBool

public func getSocketOptionBool(
    level: Int32,
    option: Int32
): Bool

功能：获取指定的套接字参数。从 IntNative 强转而来。0 => false, 非 0 => true。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE

返回值：返回指定的套接字参数。从 IntNative 强转而来。0 => false, 非 0 => true

异常：

SocketException：当 getsockopt 返回失败时或参数大小超过 IntNative 的阈值时抛出异常

func setSocketOptionBool

public func setSocketOptionBool(
    level: Int32,
    option: Int32,
    value: Bool
): Unit

功能：设置指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE
value：参数值

异常：

SocketException：当 setsockopt 返回失败时抛出异常

func toString

public override func toString(): String

功能：返回当前 UdpSocket 的状态信息。

返回值：包含当前 UdpSocket 状态信息的字符串。

class UnixSocket

public class UnixSocket <: StreamingSocket {
    public init(path: String)
    public init(address: SocketAddress)
}

UnixSocket 实例创建后应调用 connect() 接口创建连接，并且在结束时显式调用 close() 回收资源。可参阅 StreamingSocket 获取更多信息。

注：该类型不支持在 Windows 平台上运行。

init

public init(path: String)

功能：创建一个未连接的 UnixSocket 实例此文件类型可通过 isSock() 判断是否存在，可通过 unlink() 接口删除。

参数：

path：连接的文件地址

init

public init(address: SocketAddress)

功能：创建一个未连接的 UnixSocket 实例。

参数：

address：连接的套接字地址

prop remoteAddress

public override prop remoteAddress: SocketAddress

功能：Socket 已经或将要连接的远端地址。

异常：

SocketException：当 Socket 已经被关闭时抛出异常

prop localAddress

public override prop localAddress: SocketAddress

功能：Socket 将要或已经被绑定的本地地址。

异常：

SocketException：当 Socket 已经被关闭或无可用的本地地址（本地地址未配置并且套接字未连接）时抛出异常

prop readTimeout

public override mut prop readTimeout: ?Duration

功能：设置和读取读操作超时时间。

返回值：超时时间或 None。如果设置的时间过小将会设置为最小时钟周期值，过大时将设置为None，默认值为 None

异常：

IllegalArgumentException：当超时时间小于 0 时，抛出异常

prop writeTimeout

public override mut prop writeTimeout: ?Duration

功能：设置和读取写操作超时时间。

返回值：超时时间或 None。如果设置的时间过小将会设置为最小时钟周期值；过大时将设置为最大超时时间（(2⁶³-1) 纳秒）；默认值为 None

异常：

IllegalArgumentException：当超时时间小于 0 时，抛出异常

prop sendBufferSize

public mut prop sendBufferSize: Int64

功能：设置和读取 SO_SNDBUF 属性。

异常：

IllegalArgumentException：当 size 小于等于 0 时，抛出异常
SocketException：当 Socket 已关闭时，抛出异常

prop receiveBufferSize

public mut prop receiveBufferSize: Int64

功能：设置和读取 SO_RCVBUF 属性。

异常：

IllegalArgumentException：当 size 小于等于 0 时，抛出异常
SocketException：当 Socket 已关闭时，抛出异常

func read

public override func read(buffer: Array<Byte>): Int64

功能：读取报文。超时情况按 readTimeout 决定, 详见 readTimeout。

参数：

buffer：读取的数据存储变量

返回值：读取的数据长度

异常：

SocketException：当 buffer 大小为 0 时抛出异常，当因系统原因读取失败时，抛出异常

func write

public override func write(buffer: Array<Byte>): Unit

功能：读取写入。超时情况按 writeTimeout 决定，详见 writeTimeout。

参数：

buffer：写入的数据存储变量

异常：

SocketException：当 buffer 大小为 0 时抛出异常，当因系统原因写入失败时，抛出异常

func connect

public func connect(timeout!: ?Duration = None)

功能：建立远端连接，对端拒绝时连接失败，会自动绑定本地地址，因此不需要进行额外的绑定操作。

参数：

timeout：超时时间，None 表示无超时时间。Unix 与 Tcp 不同，队列已满时，调用将理解返回错误，而非重试阻塞等待

异常：

IllegalArgumentException：当远端地址不合法时抛出异常
SocketException：当连接因系统原因无法建立时抛出异常
SocketTimeoutException：当连接超时时抛出异常
IllegalArgumentException：当超时时间小于 0 时，抛出异常

func getSocketOption

public func getSocketOption(
    level: Int32,
    option: Int32,
    value: CPointer<Unit>,
    valueLength: CPointer<UIntNative>
): Unit

功能：获取指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE
value：参数值
valueLength：参数值长度

异常：

SocketException：当 getsockopt 返回失败时抛出异常

func setSocketOption

public func setSocketOption(
    level: Int32,
    option: Int32,
    value: CPointer<Unit>,
    valueLength: UIntNative
): Unit

功能：设置指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE
value：参数值
valueLength：参数值长度

异常：

SocketException：当 setsockopt 返回失败时抛出异常

func getSocketOptionIntNative

public func getSocketOptionIntNative(
    level: Int32,
    option: Int32
): IntNative

功能：获取指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE

返回值：返回指定的套接字参数值

异常：

SocketException：当 getsockopt 返回失败时或参数大小超过 IntNative 的阈值时抛出异常

func setSocketOptionIntNative

public func setSocketOptionIntNative(
    level: Int32,
    option: Int32,
    value: IntNative
): Unit

功能：设置指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE
value：参数值

异常：

SocketException：当 setsockopt 返回失败时抛出异常

func getSocketOptionBool

public func getSocketOptionBool(
    level: Int32,
    option: Int32
): Bool

功能：获取指定的套接字参数。从 IntNative 强转而来。0 => false，非 0 => true。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE

返回值：返回指定的套接字参数值。从 IntNative 强转而来。0 => false，非 0 => true

异常：

SocketException：当 getsockopt 返回失败时或参数大小超过 IntNative 的阈值时抛出异常

func setSocketOptionBool

public func setSocketOptionBool(
    level: Int32,
    option: Int32,
    value: Bool
): Unit

功能：设置指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE
value：参数值

异常：

SocketException：当 setsockopt 返回失败时抛出异常

func close

public func close(): Unit

功能：关闭套接字，所有操作除了 close/isClosed 之外，均不允许再调用。接口允许多次调用。

func isClosed

public func isClosed(): Bool

功能：判断套接字是否通过调用 close 显式关闭。

返回值：返回套接字是否已经调用 close 显示关闭。是则返回 true；否则，返回 false

func toString

public override func toString(): String

功能：返回当前 UnixSocket 的状态信息。

返回值：包含当前 UnixSocket 状态信息的字符串。

class UnixServerSocket

public class UnixServerSocket <: ServerSocket

UnixServerSocket 监听连接，创建后可以通过属性和 setSocketOptionXX 接口配置属性值。需要调用 bind() 接口绑定本地地址开始监听连接。可以通过 accept() 接口接受连接。

注：该类型不支持在 Windows 平台上运行。

prop localAddress

public override prop localAddress: SocketAddress

功能：Socket 将要或已经被绑定的本地地址。

异常：

SocketException：当 Socket 已经被关闭时抛出异常

init

public init(bindAt!: String)

功能：创建一个未连接的 UnixServerSocket 实例此文件类型可通过 isSock() 判断是否存在，可通过 unlink() 接口删除。

参数：

path：连接的文件地址

init

public init(bindAt!: SocketAddress)

功能：创建一个未连接的 UnixServerSocket 实例。

参数：

address：连接的套接字地址

prop sendBufferSize

public mut prop sendBufferSize: Int64

功能：设置和读取 SO_SNDBUF 属性。

异常：

IllegalArgumentException：当 size 小于等于 0 时，抛出异常
SocketException：当 Socket 已关闭时，抛出异常

prop receiveBufferSize

public mut prop receiveBufferSize: Int64

功能：设置和读取 SO_RCVBUF 属性。

异常：

IllegalArgumentException：当 size 小于等于 0 时，抛出异常
SocketException：当 Socket 已关闭时，抛出异常

prop backlogSize

public mut prop backlogSize: Int64

功能：设置和读取 backlog 大小。仅可在调用 bind 前调用，否则将抛出异常。变量是否生效取决于系统行为，可能不可预知得被忽略。

异常：

SocketException：当在 bind 后调用，将抛出异常

func bind

public override func bind(): Unit

功能：绑定一个 Unix domain 套接字，并创建监听队列此接口自动在本地地址中创建一个套接字文件，如该文件已存在则会绑定失败此文件类型可通过 isSock() 接口判断是否存在，可通过 unlink() 接口删除失败后需要 close 套接字，不支持多次重试。

异常：

SocketException：当因系统原因绑定失败时抛出异常

func accept

public override func accept(timeout!: ?Duration): UnixSocket

功能：等待接受一个客户端的连接，或从队列中读取连接。

参数：

timeout：超时时间

返回值：连接的客户端套接字

异常：

SocketTimeoutException：连接超时
IllegalArgumentException：当超时时间小于 0 时，抛出异常

func accept

public override func accept(): UnixSocket

功能：等待接受一个客户端的连接，或从队列中读取连接。

返回值：连接的客户端套接字

func close

public override func close(): Unit

功能：关闭套接字，该套接字的所有操作除了 close/isClosed 之外，均不允许再调用。此接口允许多次调用。

func isClosed

public override func isClosed(): Bool

功能：判断套接字是否通过调用 close 显式关闭。

func getSocketOption

public func getSocketOption(
    level: Int32,
    option: Int32,
    value: CPointer<Unit>,
    valueLength: CPointer<UIntNative>
): Unit

功能：获取指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE
value：参数值
valueLength：参数值长度

异常：

SocketException：当 getsockopt 返回失败时抛出异常

func setSocketOption

public func setSocketOption(
    level: Int32,
    option: Int32,
    value: CPointer<Unit>,
    valueLength: UIntNative
): Unit

功能：设置指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE
value：参数值
valueLength：参数值长度

异常：

SocketException：当 setsockopt 返回失败时抛出异常

func getSocketOptionIntNative

public func getSocketOptionIntNative(
    level: Int32,
    option: Int32
): IntNative

功能：获取指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE

返回值：返回指定的套接字参数值

异常：

SocketException：当 getsockopt 返回失败时或参数大小超过 IntNative 的阈值时抛出异常

func setSocketOptionIntNative

public func setSocketOptionIntNative(
    level: Int32,
    option: Int32,
    value: IntNative
): Unit

功能：设置指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE
value：参数值

异常：

SocketException：当 setsockopt 返回失败时抛出异常

func getSocketOptionBool

public func getSocketOptionBool(
    level: Int32,
    option: Int32
): Bool

功能：获取指定的套接字参数。从 IntNative 强转而来。0 => false, 非 0 => true。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE

返回值：返回指定的套接字参数。从 IntNative 强转而来。0 => false, 非 0 => true

异常：

SocketException：当 getsockopt 返回失败时或参数大小超过 IntNative 的阈值时抛出异常

func setSocketOptionBool

public func setSocketOptionBool(
    level: Int32,
    option: Int32,
    value: Bool
): Unit

功能：设置指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE
value：参数值

异常：

SocketException：当 setsockopt 返回失败时抛出异常

func toString

public override func toString(): String

功能：返回当前 UnixServerSocket 的状态信息。

返回值：包含当前 UnixServerSocket 状态信息的字符串。

class UnixDatagramSocket

public class UnixDatagramSocket <: DatagramSocket {
    public init(bindAt!: String)
    public init(bindAt!: SocketAddress)
}

UnixDatagramSocket 实例创建后，应当显式调用 bind() 接口绑定。Unix 数据包套接字不需要连接，不需要与远端握手多次。不过用户也可以通过 connect/disconnect 接口与远端建连和断连。不同于 UDP, UDS 没有数据包大小限制，限制来源于操作系统和接口实现。套接字资源需要用 close 接口显式回收。可参阅 DatagramSocket 获取更多信息。

注：该类型不支持在 Windows 平台上运行。

init

public init(bindAt!: String)

功能：创建一个未连接的 UnixDatagramSocket 实例此文件类型可通过 isSock() 判断是否存在，可通过 unlink() 接口删除。

参数：

bindAt：连接的文件地址。文件地址应当不存在，在 bind 时会创建

异常：

SocketException：当路径为空或已存在时，抛出异常

init

public init(bindAt!: SocketAddress)

功能：创建一个未连接的 UnixDatagramSocket 实例。

参数：

bindAt：连接的套接字地址。地址应当不存在，在 bind 时会创建

异常：

SocketException：当路径为空或已存在时，抛出异常

prop remoteAddress

public override prop remoteAddress: ?SocketAddress

功能：Socket 已经连接的远端地址，当 Socket 未连接时返回 None。

异常：

SocketException：当 Socket 已经被关闭时抛出异常

prop localAddress

public override prop localAddress: SocketAddress

功能：socket 将要或已经绑定的本地地址。

异常：

SocketException：当 socket 已经关闭将抛出异常

prop receiveTimeout

public override mut prop receiveTimeout: ?Duration

功能：设置和读取 receive/receiveFrom 操作超时时间。

返回值：超时时间或 None，如果设置的时间过小将会设置为最小时钟周期值；过大时将设置为最大超时时间（(2⁶³-1) 纳秒）；默认值为 None

异常：

IllegalArgumentException：当超时时间小于 0 时，抛出异常

prop sendTimeout

public override mut prop sendTimeout: ?Duration

功能：设置和读取 send/sendTo 操作超时时间。

返回值：超时时间或 None，如果设置的时间过小将会设置为最小时钟周期值；过大时将设置为最大超时时间（(2⁶³-1) 纳秒）；默认值为 None

异常：

IllegalArgumentException：当超时时间小于 0 时，抛出异常

func close

public override func close(): Unit

功能：关闭套接字，所有操作除了 close/isClosed 之外，均不允许再调用。接口允许多次调用。

func isClosed

public override func isClosed(): Bool

功能：判断套接字是否通过调用 close 显式关闭。

返回值：返回套接字是否已经通过调用 close 显式关闭。是则返回 true；否则，返回 false

func bind

public func bind(): Unit

功能：绑定一个 Unix datagram 套接字，并创建监听队列。此接口自动在本地地址中创建一个套接字文件，如该文件已存在则会绑定失败此文件类型可通过 isSock() 判断是否存在，可通过 unlink() 接口删除失败后需要 close 套接字，不支持多次重试。

异常：

SocketException：当文件地址已存在，或文件创建失败将抛出异常

func connect

public func connect(remotePath: String): Unit

功能：连接特定远端地址，可通过 disconnect 撤销配置。仅接受该远端地址的报文。必须在 bind 后调用。此操作执行后，端口将开始接收 ICMP 报文，若收到异常报文后，可能导致 send/sendTo 执行失败。

参数：

remotePath：远端文件地址

异常：

SocketException：当地址未绑定时，将抛出异常

func connect

public func connect(remote: SocketAddress): Unit

功能：连接特定远端地址，可通过 disconnect 撤销配置。仅接受该远端地址的报文。默认执行 bind，因此不需额外调用 bind。此操作执行后，端口将开始接收 ICMP 报文，若收到异常报文后，可能导致 send/sendTo 执行失败。

参数：

remote：远端套接字地址

异常：

SocketException：当地址未绑定时，将抛出异常

func disconnect

public func disconnect(): Unit

功能：停止连接。取消仅收取特定对端报文。可在 connect 前调用，可多次调用。

异常：

SocketException：当未绑定时抛出异常

func receiveFrom

public override func receiveFrom(buffer: Array<Byte>): (SocketAddress, Int64)

功能：收取报文。

参数：

buffer：存储收取到报文的地址

返回值：收取到的报文的发送端地址，及实际收取到的报文大小，可能为 0 或者大于参数 buffer 的大小

异常：

SocketException：本机缓存过小无法读取报文时，抛出异常
SocketTimeoutException：读取超时时抛出异常

func sendTo

public override func sendTo(recipient: SocketAddress, payload: Array<Byte>): Unit

功能：发送报文。当没有足够的缓存地址时可能会被阻塞。

参数：

recipient：发送的对端地址
payload：发送报文内容

异常：

SocketException：当 payload 的大小超出系统限制
SocketException：系统发送失败，例如：当 connect 被调用，并且收到异常 ICMP 报文时，发送将失败
SocketException：macOS 平台下当 connect 被调用后调用 sendTo, 将抛出异常

func send

public func send(payload: Array<Byte>): Unit

功能：发送报文到 connect 连接到的地址。

参数：

payload：发送报文内容

异常：

SocketException：当 payload 的大小超出系统限制
SocketException：系统发送失败，例如：当 connect 被调用，并且收到异常 ICMP 报文时，发送将失败

func receive

public func receive(buffer: Array<Byte>): Int64

功能：从 connect 连接到的地址收取报文。

参数：

buffer：存储收取到的报文的地址

返回值：收取到的报文大小

prop sendBufferSize

public mut prop sendBufferSize: Int64

功能：设置和读取 SO_SNDBUF 属性，提供一种方式指定发包缓存大小。选项的生效情况取决于系统。

异常：

IllegalArgumentException：当 size 小于等于 0 时，抛出异常
SocketException：当 Socket 已关闭时，抛出异常

prop receiveBufferSize

public mut prop receiveBufferSize: Int64

功能：设置和读取 SO_RCVBUF 属性，提供一种方式指定发包缓存大小。选项的生效情况取决于系统。

异常：

IllegalArgumentException：当 size 小于等于 0 时，抛出异常
SocketException：当 Socket 已关闭时，抛出异常

func getSocketOption

public func getSocketOption(
    level: Int32,
    option: Int32,
    value: CPointer<Unit>,
    valueLength: CPointer<UIntNative>
): Unit

功能：获取指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE
value：参数值
valueLength：参数值长度

异常：

SocketException：当 getsockopt 返回失败时抛出异常

func setSocketOption

public func setSocketOption(
    level: Int32,
    option: Int32,
    value: CPointer<Unit>,
    valueLength: UIntNative
): Unit

功能：设置指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE
value：参数值
valueLength：参数值长度

异常：

SocketException：当 setsockopt 返回失败时抛出异常

func getSocketOptionIntNative

public func getSocketOptionIntNative(
    level: Int32,
    option: Int32
): IntNative

功能：获取指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE

返回值：返回指定的套接字参数值

异常：

SocketException：当 getsockopt 返回失败时或参数大小超过 IntNative 的阈值时抛出异常

func setSocketOptionIntNative

public func setSocketOptionIntNative(
    level: Int32,
    option: Int32,
    value: IntNative
): Unit

功能：设置指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE
value：参数值

异常：

SocketException：当 setsockopt 返回失败时抛出异常

func getSocketOptionBool

public func getSocketOptionBool(
    level: Int32,
    option: Int32
): Bool

功能：获取指定的套接字参数。从 IntNative 强转而来。0 => false, 非 0 => true。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE

返回值：返回指定的套接字参数值。从 IntNative 强转而来。0 => false, 非 0 => true

异常：

SocketException：当 getsockopt 返回失败时抛出异常

func setSocketOptionBool

public func setSocketOptionBool(
    level: Int32,
    option: Int32,
    value: Bool
): Unit

功能：设置指定的套接字参数。

参数：

level：层级，例如 SOL_SOCKET
option：参数，例如 SO_KEEPALIVE
value：参数值

异常：

SocketException：当 setsockopt 返回失败抛出异常

func toString

public override func toString(): String

功能：返回当前 UDS 的状态信息。

返回值：包含当前 UDS 状态信息的字符串。

enum SocketNet

public enum SocketNet <: ToString & Equatable<SocketNet> {
    | TCP
    | UDP
    | UNIX
}

传输层协议类型。

TCP

TCP

功能：TCP。

UDP

UDP

功能：UDP。

UNIX

UNIX

功能：UNIX。

func toString

public func toString(): String

功能：将枚举值转换为字符串。

返回值：返回转换后字符串

operator func ==

public operator func ==(that: SocketNet): Bool

功能：判断两个 SocketNet 是否相等。

参数：

that：传入 SocketNet

返回值：如果相等，则返回 true；否则，返回 false

operator func !=

public operator func !=(that: SocketNet): Bool

功能：判断两个 SocketNet 是否不相等。

参数：

that：传入 SocketNet

返回值：如果不相等，则返回 true；否则，返回 false

enum SocketAddressKind

public enum SocketAddressKind <: ToString & Equatable<SocketAddressKind> {
    | IPv4
    | IPv6
    | Unix
}

互联网通信协议种类。

IPv4

IPv4

功能：IPv4。

IPv6

IPv6

功能：IPv6。

Unix

Unix

功能：Unix。

func toString

public func toString(): String

功能：将枚举值转换为字符串。

返回值：返回转换后字符串

operator func ==

public operator func ==(that: SocketAddressKind): Bool

功能：判断两个 SocketAddressKind 是否相等。

参数：

that：传入 SocketAddressKind

返回值：如果相等，则返回 true；否则，返回 false

operator func !=

public operator func !=(that: SocketAddressKind): Bool

功能：判断两个 SocketAddressKind 是否不相等。

参数：

that：传入 SocketAddressKind

返回值：如果不相等，则返回 true；否则，返回 false

struct SocketKeepAliveConfig

public struct SocketKeepAliveConfig <: ToString & Equatable<SocketKeepAliveConfig> {
    public let idle: Duration
    public let interval: Duration
    public let count: UInt32
    public init(
        idle!: Duration = Duration.second * 45,
        interval!: Duration = Duration.second * 5,
        count!: UInt32 = 5
    )
    public init(
        idleSeconds: UInt32,
        intervalSeconds: UInt32,
        count: UInt32
    )
}

TCP KeepAlive 属性配置

init

public init(
    idle!: Duration = Duration.second * 45,
    interval!: Duration = Duration.second * 5,
    count!: UInt32 = 5
)

功能：初始化 SocketKeepAliveConfig 实例对象。

参数：

idle：允许空闲的时长，默认 45 秒
interval：保活报文发送周期，默认 45 秒
count：查询连接是否失效的报文个数，默认 5 个

异常：

IllegalArgumentException：当配置为空闲状态或设置间隔小于 0 时抛出异常

idle

public let idle: Duration

功能：允许连接空闲的时长，空闲超长将关闭连接。

interval

public let interval: Duration

功能：保活报文发送周期。

count

public let count: UInt32

功能：查询连接是否失效的报文个数。

func toString

public override func toString(): String

功能：将 TCP KeepAlive 属性配置转换为字符串。

返回值：返回转换后字符串

operator func ==

public override operator func ==(other: SocketKeepAliveConfig): Bool

功能：判断两个 SocketKeepAliveConfig 实例是否相等。

参数：

other：参与比较的 SocketKeepAliveConfig 实例。

返回值：如果相等，则返回 true；否则，返回 false

operator func !=

public override operator func !=(other: SocketKeepAliveConfig): Bool

功能：判断两个 SocketKeepAliveConfig 实例是否不等。

参数：

other：参与比较的 SocketKeepAliveConfig 实例。

返回值：如果不等，则返回 true；否则，返回 false

class SocketAddress

public open class SocketAddress <: ToString & Hashable & Equatable<SocketAddress> {
    public init(kind: SocketAddressKind, address: Array<UInt8>, port: UInt16)
    public init(hostAddress: String, port: UInt16)
    public init(unixPath!: String)
}

具有特定类型、地址和端口的套接字地址。

init

public init(kind: SocketAddressKind, address: Array<UInt8>, port: UInt16)

功能：初始化 SocketAddress。

参数：

kind：套接字地址类型
address：IP 地址
port：端口号

异常：

SocketException：当地址长度不符合地址类型要求时抛出异常

init

public init(hostAddress: String, port: UInt16)

功能：初始化 SocketAddress。

参数：

hostAddress：IP 地址
port：端口号

异常：

SocketException：当地址无法解析成 IP 格式，或不符合地址类型要求时抛出异常

init

public init(unixPath!: String)

功能：初始化 SocketAddress。

参数：

unixPath：连接的文件地址

异常：

SocketException：当地址无法解析成 IP 格式，或不符合地址类型要求时抛出异常

prop address

public prop address: Array<UInt8>

功能：获取地址。

返回值：获取存储在数组中的地址

prop hostAddress

public prop hostAddress: String

功能：获取主机地址。

返回值：获取由字符串表示的主机地址

prop hostName

public prop hostName: Option<String>

功能：获取名称，不存在时返回 None。

prop kind

public prop kind: SocketAddressKind

功能：获取地址类型。

返回值：返回地址类型

prop port

public prop port: UInt16

功能：获取端口。

返回值：返回端口

prop zone

public prop zone: Option<String>

功能：获取 IPv6 地址族。

返回值：如果 IPv6 地址族存在，返回 IPv6 地址族，否则返回 None

prop defaultMask

public prop defaultMask: Option<IPMask>

功能：获取默认掩码。

返回值：如果默认掩码存在，返回默认掩码，否则返回 None

func mask

public func mask(mask: IPMask): SocketAddressWithMask

功能：使用掩码处理地址。

参数：

mask：掩码

返回值：被处理后的地址

异常：

SocketException：当掩码长度不符合地址长度时，抛出异常
IllegalArgumentException：当缓存空间不符合 IPv4/IPv6 要求时

func toString

public open func toString(): String

功能：获取地址对象字符串，格式为："127.0.0.1:2048"， "[::]:2048"，"[212c:3742::ffff:5863:6f00]:2048" 等。

异常：

SocketException：地址不合法时，抛出异常

func hashCode

public open func hashCode(): Int64

功能：获取 hashcode 值。

返回值：返回 hashcode 值

operator func ==

public operator func ==(that: SocketAddress): Bool

功能：判断两个 SocketAddress 是否相等。

参数：

that：传入 SocketAddress

返回值：如果相等，则返回 true；否则，返回 false

operator func !=

public operator func != (that: SocketAddress): Bool

功能：判断两个 SocketAddress 是否不相等。

参数：

that：传入 SocketAddress

返回值：如果不相等，则返回 true；否则，返回 false

func kapString

public func kapString(): String

功能：获取 IP 协议、地址和端口字符串。

返回值：返回 IP 协议、地址和端口字符串

异常：

SocketException：地址的大小与 IPv4 或 IPv6 不匹配时，抛出异常

func setHostName

public func setHostName(name: String): Unit

功能：设置主机名。

func resolve

public static func resolve(domain: String, port: UInt16): ?SocketAddress

功能：解析域和端口，并构造 SocketAddress 的实例。当传入 IP 地址时，不包含 DNS 能力。当传入域名地址时，通过 getaddrinfo 解析得到 IP 地址，其中优先解析 IPv4 地址，并仅返回获取到的首个 IP 地址。

参数：

domain：域
port：端口

返回值：如果解析域和端口成功，返回 SocketAddress 实例，否则返回 None

class SocketAddressWithMask

public class SocketAddressWithMask <: SocketAddress {
    public init(kind: SocketAddressKind, address: Array<UInt8>, port: UInt16, mask: IPMask)
    public init(hostAddress: String, port: UInt16, mask: IPMask)
    public init(socketAddr: SocketAddress, mask: IPMask)
}

带有掩码的 SocketAddress。

init

public init(kind: SocketAddressKind, address: Array<UInt8>, port: UInt16, mask: IPMask)

功能：初始化 SocketAddressWithMask。

参数：

kind：SocketAddress 类型
address：符合 kind 所指定类型的地址
port：端口
mask：掩码

异常：

SocketException：当参数 address 传入的地址不符合参数 kind 地址类型的要求时，抛出异常

init

public init(hostAddress: String, port: UInt16, mask: IPMask)

功能：初始化 SocketAddressWithMask。

参数：

hostAddress：IP 地址字符串
port：端口
mask：掩码

异常：

SocketException：当参数 address 无法解析成合法的 IP 地址

init

public init(socketAddr: SocketAddress, mask: IPMask)

功能：初始化 SocketAddressWithMask。

参数：

socketAddr：地址
mask：掩码

异常：

SocketException：当参数 socketAddr 不合法

prop ipMask

public mut prop ipMask: IPMask

功能：设置/获取 IP 掩码。

返回值：返回 IP 掩码

func clone

public func clone(): SocketAddressWithMask

功能：使用绑定的掩码处理地址，复制一个地址。

返回值：复制生成的 SocketAddressWithMask 实例

异常：

SocketException：当掩码长度不符合地址长度
IllegalArgumentException：当缓存长度不足

func toString

public override func toString(): String

功能：将 SocketAddressWithMask 转换为字符串。

返回值：返回转换后字符串

func hashCode

public override func hashCode(): Int64

功能：获取 SocketAddressWithMask 的 hashcode 值。

返回值：返回 SocketAddressWithMask 的 hashcode 值

class IPMask

public class IPMask <: ToString {
    public init(buf: Array<UInt8>)
    public init(ones: Int64, bits: Int64)
    public init(a: UInt8, b: UInt8, c: UInt8, d: UInt8)
}

IP 掩码，操作 IP 地址和路由地址。

init

public init(buf: Array<UInt8>)

功能：初始化掩码值。

参数：

buf：掩码值

异常：

IllegalArgumentException：当 buffer 值超出阈值，不符合 IPv4/IPv6 要求

init

public init(ones: Int64, bits: Int64)

功能：初始化掩码值。

参数：

ones：高位 1 的个数
bits：bit 位总个数

异常：

IllegalArgumentException：当 bits 值超出阈值，不符合 IPv4/IPv6 要求

init

public init(a: UInt8, b: UInt8, c: UInt8, d: UInt8)

功能：初始化掩码值，参数值分别是 IPv4 的 4 个字节 a.b.c.d。

参数：

a：最高字节
b：次高字节
c：次低字节
d：最低字节

func size

public func size(): (Int64, Int64)

功能：获取高位 1 的个数，以及总 bit 位数。

返回值：高位 1 的个数，以及总 bit 位数，若掩码格式不符合高位均为 1 的格式，返回 (0, 0)

func toString

public func toString(): String

功能：将IP 掩码转换为字符串。

返回值：返回转换后字符串

struct SocketOptions

public struct SocketOptions {
    public static const SOL_SOCKET: Int32 = SOL_SOCKET
    public static const IPPROTO_TCP: Int32 = IPPROTO_TCP
    public static const IPPROTO_UDP: Int32 = IPPROTO_UDP

    public static const SO_KEEPALIVE: Int32 = SOCK_KEEPALIVE
    public static const TCP_NODELAY: Int32 = SOCK_TCP_NODELAY
    public static const TCP_QUICKACK: Int32 = SOCK_TCP_QUICKACK

    public static const SO_LINGER: Int32 = SOCK_LINGER
    public static const SO_SNDBUF: Int32 = SOCK_SNDBUF
    public static const SO_RCVBUF: Int32 = SOCK_RCVBUF

    public static const SO_REUSEADDR: Int32 = SOCK_REUSEADDR
    public static const SO_REUSEPORT: Int32 = SOCK_REUSEPORT
    public static const SO_BINDTODEVICE: Int32 = SOCK_BINDTODEVICE
}

struct SocketOptions 存储了设置套接字选项的一些参数常量方便后续调用。

SOL_SOCKET

public static const SOL_SOCKET: Int32 = SOL_SOCKET

常数，用于将套接字选项的 level 层级设为 SOL_SOCKET。

IPPROTO_TCP

public static const IPPROTO_TCP: Int32 = IPPROTO_TCP

常数，用于将套接字选项的 level 层级设为 IPPROTO_TCP。

IPPROTO_UDP

public static const IPPROTO_UDP: Int32 = IPPROTO_UDP

常数，用于将套接字选项的 level 层级设为 IPPROTO_UDP。

SO_KEEPALIVE

public static const SO_KEEPALIVE: Int32 = SOCK_KEEPALIVE

常数，用于将套接字选项的 optname 设为 SO_KEEPALIVE。

TCP_NODELAY

public static const TCP_NODELAY: Int32 = SOCK_TCP_NODELAY

常数，用于将套接字选项的 optname 设为 TCP_NODELAY。

TCP_QUICKACK

public static const TCP_QUICKACK: Int32 = SOCK_TCP_QUICKACK

常数，用于将套接字选项的 optname 设为 TCP_QUICKACK。

SO_LINGER

public static const SO_LINGER: Int32 = SOCK_LINGER

常数，用于将套接字选项的 optname 设为 SO_LINGER。

SO_SNDBUF

public static const SO_SNDBUF: Int32 = SOCK_SNDBUF

常数，用于将套接字选项的 optname 设为 SO_SNDBUF。

SO_RCVBUF

public static const SO_RCVBUF: Int32 = SOCK_RCVBUF

常数，用于将套接字选项的 optname 设为 SO_RCVBUF。

SO_REUSEADDR

public static const SO_REUSEADDR: Int32 = SOCK_REUSEADDR

常数，用于将套接字选项的 optname 设为 SO_REUSEADDR。

SO_REUSEPORT

public static const SO_REUSEPORT: Int32 = SOCK_REUSEPORT

常数，用于将套接字选项的 optname 设为 SO_REUSEPORT。

SO_BINDTODEVICE

public static const SO_BINDTODEVICE: Int32 = SOCK_BINDTODEVICE

常数，用于将套接字选项的 optname 设为 SO_BINDTODEVICE。

class RawSocket

public class RawSocket {
    public init(domain: SocketDomain, `type`: SocketType, protocol: ProtocolType)
}

RawSocket 提供了套接字的基本功能，可以访问特定通信域（domain）、类型（type）和协议（protocol）组合的套接字。Socket 包已经提供了 TCP、 UDP 等常用网络协议的支持，因此，该类型适用于已经支持以外的网络编程需求。

注意：当前 RawSocket 已经验证的功能包括 TCP、UDP、UDS 以及 ICMP 协议套接字，其它类型使用上可能存在预期之外的问题。此外，由于接口的开放性，可以使用 connect 再 listen 的组合，部分场景可能存在预期外的问题，请开发者使用时遵循正常的调用逻辑，避免产生问题。

init

public init(domain: SocketDomain, `type`: SocketType, protocol: ProtocolType)

功能：创建特定通信域、类型、协议组合的套接字。

参数：

domain：通信域
type：套接字类型
protocol：协议类型

异常：

SocketException：通信域、类型、协议组合无法创建套接字

prop localAddr

public prop localAddr: RawAddress

功能：获取当前 RawSocket 实例的本地地址。

返回值：当前 RawSocket 实例的本地地址

异常：

SocketException：当前 RawSocket 实例已经关闭，或无法获取本地地址

prop remoteAddr

public prop remoteAddr: RawAddress

功能：获取当前 RawSocket 实例的对端地址。

返回值：当前 RawSocket 实例的对端地址

异常：

SocketException：当前 RawSocket 实例已经关闭，或无法获取对端地址

prop readTimeout

public mut prop readTimeout: ?Duration

功能：获取或设置当前 RawSocket 实例的读超时时间。

异常：

SocketException：当前 RawSocket 实例已经关闭
IllegalArgumentException：设置的读超时时间为负

prop writeTimeout

public mut prop writeTimeout: ?Duration

功能：获取或设置当前 RawSocket 实例的写超时时间。

异常：

SocketException：当前 RawSocket 实例已经关闭
IllegalArgumentException：设置的写超时时间为负

func bind

public func bind(addr: RawAddress): Unit

功能：将当前 RawSocket 实例与指定的套接字地址进行绑定。

参数：

addr：套接字地址

异常：

SocketException：当前 RawSocket 实例已经关闭，或绑定失败

func listen

public func listen(backlog: Int32): Unit

功能：监听当前 RawSocket 实例绑定的地址。

参数：

backlog：等待队列增长的最大长度

异常：

SocketException：当前 RawSocket 实例已经关闭，或监听失败

func accept

public func accept(timeout!: ?Duration = None): RawSocket

功能：接收当前 RawSocket 实例监听时挂起连接队列上的第一个连接请求，返回一个用于通信的 RawSocket。

参数：

timeout：等待连接请求的最大时间，默认值 None 表示一直等待

异常：

SocketException：当前 RawSocket 实例已经关闭，或接收失败
SocketTimeoutException：等待超时

返回值：用于通信的新 RawSocket 实例

func connect

public func connect(addr: RawAddress, timeout!: ?Duration = None): Unit

功能：向目标地址发送连接请求。

参数：

addr：发送连接请求的目标地址
timeout：等待连接接收的最大时间，默认值 None 表示一直等待

异常：

SocketException：当前 RawSocket 实例已经关闭，或请求失败
SocketTimeoutException：等待超时

func close

public func close(): Unit

功能：关闭。

func sendTo

public func sendTo(addr: RawAddress, buffer: Array<Byte>, flags: Int32): Unit

功能：向目标地址发送数据。若 RawSocket 是 DATAGRAM 类型，发送的数据包大小不允许超过 65507 字节。

参数：

addr：发送数据的目标地址
buffer：数据
flags：指定函数行为的标志

异常：

SocketException：当前 RawSocket 实例已经关闭，或发送数据失败
SocketTimeoutException：超过指定的写超时时间
SocketException：macOS 平台下当 connect 被调用后调用 sendTo, 将抛出异常

func receiveFrom

public func receiveFrom(buffer: Array<Byte>, flags: Int32): (RawAddress, Int64)

功能：接收来自其它 RawSocket 实例的数据。

参数：

buffer：存储接收数据的数组
flags：指定函数行为的标志

返回值：数据来源的地址和数据长度

异常：

SocketException：当前 RawSocket 实例已经关闭，或接收数据失败
SocketTimeoutException：超过指定的读超时时间

func send

public func send(buffer: Array<Byte>, flags: Int32): Unit

功能：向连接的对端发送数据。

参数：

buffer：数据
flags：指定函数行为的标志

异常：

SocketException：当前 RawSocket 实例已经关闭，或发送数据失败
SocketTimeoutException：超过指定的写超时时间

func receive

public func receive(buffer: Array<Byte>, flags: Int32): Int64

功能：接收来自连接对端发送的数据。

参数：

buffer：存储接收数据的数组
flags：指定函数行为的标志

返回值：数据长度

异常：

SocketException：当前 RawSocket 实例已经关闭，或发送数据失败
SocketTimeoutException：超过指定的读超时时间

func setSocketOption

public unsafe func setSocketOption(level: Int32, option: Int32, value: CPointer<Byte>, len: Int32): Unit

功能：设置套接字选项。

参数：

level：套接字选项级别
option：套接字选项名
value：套接字选项值
len：套接字选项字节长度

异常：

SocketException：当前 RawSocket 实例已经关闭，或设置套接字选项失败

func getSocketOption

public unsafe func getSocketOption(level: Int32, option: Int32, value: CPointer<Byte>, len: CPointer<Int32>): Unit

功能：获取套接字选项的值。

参数：

level：套接字选项级别
option：套接字选项名
value：存储套接字选项值的指针
len：套接字选项值的长度

异常：

SocketException：当前 RawSocket 实例已经关闭，或获取套接字选项失败

struct SocketDomain

public struct SocketDomain <: Equatable<SocketDomain> & ToString & Hashable {
    public static let IPV4: SocketDomain
    public static let IPV6: SocketDomain
    public static let UNIX: SocketDomain
    public static let NETLINK: SocketDomain
    public static let PACKET: SocketDomain
    public init(domain: Int32)
}

提供了常用的套接字通信域，以及通过指定 Int32 值来构建套接字通信域的功能。

IPV4

public static let IPV4: SocketDomain

功能：IPV4 通信域。

IPV6

public static let IPV6: SocketDomain

功能：IPV6 通信域。

UNIX

public static let UNIX: SocketDomain

功能：本机通信。

NETLINK

public static let NETLINK: SocketDomain

功能：内核和用户空间进程之间通信。

注意：该常量在 Windows 平台不提供。

PACKET

public static let PACKET: SocketDomain

功能：允许用户空间程序直接访问网络数据包。

注意：该常量在 Windows 平台不提供。

init

public init(domain: Int32)

功能：根据指定通信域值创建套接字通信域。

operator func ==

public operator func ==(r: SocketDomain): Bool

功能：比较两个 SocketDomain 实例是否相等。

返回值：当二者代表的 Int32 值相等时，返回 true；否则，返回 false。

operator func !=

public operator func !=(r: SocketDomain): Bool

功能：比较两个 SocketDomain 实例是否不等。

返回值：当二者代表的 Int32 值不等时，返回 true；否则，返回 false。

func toString

public func toString(): String

功能：返回当前 SocketDomain 实例的字符串表示。

返回值：当前 SocketDomain 实例的字符串表示

func hashCode

public func hashCode(): Int64

功能：返回当前 SocketDomain 实例的哈希值。

返回值：当前 SocketDomain 实例的哈希值

struct SocketType

public struct SocketType <: Equatable<SocketType> & ToString & Hashable {
    public static let STREAM: SocketType
    public static let DATAGRAM: SocketType
    public static let RAW: SocketType
    public static let SEQPACKET: SocketType
    public init(`type`: Int32)
}

提供了常用的套接字类型，以及通过指定 Int32 值来构建套接字类型的功能。

STREAM

public static let STREAM: SocketType

功能：流式套接字类型。

DATAGRAM

public static let DATAGRAM: SocketType

功能：数据报套接字类型。

RAW

public static let RAW: SocketType

功能：原始套接字类型。

SEQPACKET

public static let SEQPACKET: SocketType

功能：有序数据包套接字类型。

init

public init(`type`: Int32)

功能：通过指定套接字类型值创建套接字类型。

operator func ==

public operator func ==(r: SocketType): Bool

功能：判断两个 SocketType 实例是否相等。

返回值：当二者代表的 Int32 值相等时，返回 true；否则，返回 false

operator func !=

public operator func !=(r: SocketType): Bool

功能：判断两个 SocketType 实例是否不等。

返回值：当二者代表的 Int32 值不等时，返回 true；否则，返回 false

func toString

public func toString(): String

功能：返回当前 SocketType 实例的字符串表示。

返回值：当前 SocketType 实例的字符串表示

func hashCode

public func hashCode(): Int64

功能：返回当前 SocketType 实例的哈希值。

返回值：当前 SocketType 实例的哈希值

struct ProtocolType

public struct ProtocolType <: Equatable<ProtocolType> & ToString & Hashable {
    public static let Unspecified: ProtocolType
    public static let IPV4: ProtocolType
    public static let IPV6: ProtocolType
    public static let ICMP: ProtocolType
    public static let TCP: ProtocolType
    public static let UDP: ProtocolType
    public static let RAW: ProtocolType
    public init(protocol: Int32)
}

提供了常用的套接字协议，以及通过指定 Int32 值来构建套接字协议的功能。

Unspecified

public static let Unspecified: ProtocolType

功能：不指定协议。

IPV4

public static let IPV4: ProtocolType

功能：指定协议类型为 IPV4 。

IPV6

public static let IPV6: ProtocolType

功能：指定协议类型为 IPV6。

ICMP

public static let ICMP: ProtocolType

功能：指定协议类型为 ICMP。

TCP

public static let TCP: ProtocolType

功能：指定协议类型为 TCP。

UDP

public static let UDP: ProtocolType

功能：指定协议类型为 UDP。

RAW

public static let RAW: ProtocolType

功能：指定协议类型为 RAW。

init

public init(protocol: Int32)

功能：通过指定套接字协议值创建协议。

operator func ==

public operator func ==(r: ProtocolType): Bool

功能：判断两个 ProtocolType 实例是否相等。

返回值：当二者代表的 Int32 值相等时，返回 true；否则，返回 false

operator func !=

public operator func !=(r: ProtocolType): Bool

功能：判断两个 ProtocolType 实例是否不等。

返回值：当二者代表的 Int32 值不等时，返回 true；否则，返回 false

func toString

public func toString(): String

功能：返回当前 ProtocolType 实例的字符串表示。

返回值：当前 ProtocolType 实例的字符串表示

func hashCode

public func hashCode(): Int64

功能：返回当前 ProtocolType 实例的哈希值。

返回值：当前 ProtocolType 实例的哈希值

struct OptionLevel

public struct OptionLevel {
    public static const IP: Int32
    public static const TCP: Int32
    public static const UDP: Int32
    public static const ICMP: Int32
    public static const RAW: Int32
    public static const SOCKET: Int32
}

提供了常用的套接字选项级别。

IP

public static const IP: Int32

功能：控制 IP 协议行为的套接字选项级别。

TCP

public static const TCP: Int32

功能：控制 TCP 协议行为的套接字选项级别。

UDP

public static const UDP: Int32

功能：控制 UDP 协议行为的套接字选项级别。

ICMP

public static const ICMP: Int32

功能：控制 ICMP 协议行为的套接字选项级别。

RAW

public static const RAW: Int32

功能：控制 IP 协议行为的套接字选项级别。

SOCKET

public static const SOCKET: Int32

功能：控制基本套接字行为的套接字选项级别。

struct OptionName

public struct OptionName {
    public static const IP_HDRINCL: Int32
    public static const IP_TOS: Int32
    public static const IP_TTL: Int32
    public static const TCP_KEEPCNT: Int32
    public static const TCP_KEEPIDLE: Int32
    public static const TCP_KEEPINTVL: Int32
    public static const TCP_NODELAY: Int32
    public static const SO_DEBUG: Int32
    public static const SO_ACCEPTCONN: Int32
    public static const SO_REUSEADDR: Int32
    public static const SO_KEEPALIVE: Int32
    public static const SO_DONTROUTE: Int32
    public static const SO_BROADCAST: Int32
    public static const SO_LINGER: Int32
    public static const SO_OOBINLINE: Int32
    public static const SO_SNDBUF: Int32
    public static const SO_RCVBUF: Int32
    public static const SO_SNDTIMEO: Int32
    public static const SO_RCVTIMEO: Int32
    public static const SO_ERROR: Int32
}

提供了常用的套接字选项。

IP_HDRINCL

public static const IP_HDRINCL: Int32

功能：用于在发送数据包时指定 IP 头部是否由应用程序提供的套接字选项。

IP_TOS

public static const IP_TOS: Int32

功能：用于指定数据包服务类型和优先级的套接字选项。

IP_TTL

public static const IP_TTL: Int32

功能：用于限制IP数据包在网络中传输最大跳数的套接字选项。

TCP_KEEPCNT

public static const TCP_KEEPCNT: Int32

功能：用于控制 TCP 连接中发送保持存活探测报文次数的套接字选项。

TCP_KEEPIDLE

public static const TCP_KEEPIDLE: Int32

功能：用于设置在没有收到对端确认的情况下，TCP 保持连接最大次数的套接字选项。

TCP_KEEPINTVL

public static const TCP_KEEPINTVL: Int32

功能：用于设置 TCP 保持连接时发送探测报文时间间隔的套接字选项。

TCP_NODELAY

public static const TCP_NODELAY: Int32

功能：用于控制 TCP 协议延迟行为的套接字选项。

SO_DEBUG

public static const SO_DEBUG: Int32

功能：用于启用或禁用调试模式的套接字选项。

SO_ACCEPTCONN

public static const SO_ACCEPTCONN: Int32

功能：用于查询套接字是否处于监听状态的套接字选项。

SO_REUSEADDR

public static const SO_REUSEADDR: Int32

功能：用于在套接字关闭后立即释放其绑定端口，以便其他套接字可以立即绑定该端口的套接字选项。

SO_KEEPALIVE

public static const SO_KEEPALIVE: Int32

功能：用于检测 TCP 连接是否仍然处于活动状态的套接字选项。

SO_DONTROUTE

public static const SO_DONTROUTE: Int32

功能：用于在连接套接字时，不路由套接字数据包的套接字选项。

SO_BROADCAST

public static const SO_BROADCAST: Int32

功能：用于设置套接字是否允许发送广播消息的套接字选项。

SO_LINGER

public static const SO_LINGER: Int32

功能：用于设置套接字关闭时行为的套接字选项。

SO_OOBINLINE

public static const SO_OOBINLINE: Int32

功能：用于控制接收带外数据方式的套接字选项。

SO_SNDBUF

public static const SO_SNDBUF: Int32

功能：用于设置套接字发送缓冲区大小的套接字选项。

SO_RCVBUF

public static const SO_RCVBUF: Int32

功能：用于设置套接字接收缓冲区大小的套接字选项。

SO_SNDTIMEO

public static const SO_SNDTIMEO: Int32

功能：用于设置套接字发送数据超时时间的套接字选项。

SO_RCVTIMEO

public static const SO_RCVTIMEO: Int32

功能：用于设置套接字接收数据超时时间的套接字选项。

SO_ERROR

public static const SO_ERROR: Int32

功能：获取和清除套接字上错误状态的套接字选项。

struct RawAddress

public struct RawAddress {
    public init(addr: Array<Byte>)
}

提供了 RawSocket 的通信地址创建和获取功能。

init

public init(addr: Array<Byte>)

功能：创建地址。

参数：

addr：存储地址的字节数组

prop addr

public prop addr: Array<Byte>

功能：获取地址。

class SocketException

public class SocketException <: Exception {
    public init()
    public init(message: String)
}

在出现套接字异常时抛出的异常。

init

public init()

功能：创建 SocketException 实例

init

public init(message: String)

功能：创建 SocketException 实例

参数：

message：异常提示信息

class SocketTimeoutException

public class SocketTimeoutException <: Exception {
    public init()
    public init(message: String)
}

在套接字操作超时时抛出的异常。

init

public init()

功能：创建 SocketTimeoutException 实例

init

public init(message: String)

功能：创建 SocketTimeoutException 实例

参数：

message：异常提示信息

示例

TCP 的使用

简单的 TCP 服务端和客户端示例

from std import socket.*
from std import time.*
from std import sync.*

let SERVER_PORT: UInt16 = 33333

func runTcpServer() {
    try (serverSocket = TcpServerSocket(bindAt: SERVER_PORT)) {
        serverSocket.bind()

        try (client = serverSocket.accept()) {
            let buf = Array<Byte>(10, item: 0)
            let count = client.read(buf)

            // Server read 3 bytes: [1, 2, 3, 0, 0, 0, 0, 0, 0, 0]
            println("Server read ${count} bytes: ${buf}")
        }
    }
}

main(): Int64 {
    spawn {
        runTcpServer()
    }
    sleep(Duration.millisecond * 500)

    try (socket = TcpSocket("127.0.0.1", SERVER_PORT)) {
        socket.connect()

        socket.write(Array<Byte>([1, 2, 3]))
    }

    return 0
}

运行结果如下:

Server read 3 bytes: [1, 2, 3, 0, 0, 0, 0, 0, 0, 0]

UDP 的使用

from std import socket.*
from std import time.*
from std import sync.*

let SERVER_PORT: UInt16 = 33333

func runUpdServer() {
    try (serverSocket = UdpSocket(bindAt: SERVER_PORT)) {
        serverSocket.bind()

        let buf = Array<Byte>(3, item: 0)

        let (clientAddr, count) = serverSocket.receiveFrom(buf)
        let sender = clientAddr.hostAddress

        // Server receive 3 bytes: [1, 2, 3] from 127.0.0.1
        println("Server receive ${count} bytes: ${buf} from ${sender}")
    }
}

main(): Int64 {
    spawn {
        runUpdServer()
    }
    sleep(Duration.second)

    try (udpSocket = UdpSocket(bindAt: 0)) { // random port
        udpSocket.sendTimeout = Duration.second * 2
        udpSocket.bind()
        udpSocket.sendTo(
            SocketAddress("127.0.0.1", SERVER_PORT),
            Array<Byte>([1, 2, 3])
        )
    }

    return 0
}

运行结果如下:

Server receive 3 bytes: [1, 2, 3] from 127.0.0.1

Unix 的使用

from std import socket.*
from std import time.*
from std import sync.*

let SOCKET_PATH = "/tmp/tmpsock"

func runUnixServer() {
    try (serverSocket = UnixServerSocket(bindAt: SOCKET_PATH)) {
        serverSocket.bind()

        try (client = serverSocket.accept()) {
            client.write(b"hello")
        }
    }
}

main(): Int64 {
    spawn {
        runUnixServer()
    }
    sleep(Duration.second)

    try (socket = UnixSocket(SOCKET_PATH)) {
        socket.connect()

        let buf = Array<Byte>(10, item: 0)
        socket.read(buf)

        println(String.fromUtf8(buf)) // hello
    }

    return 0
}

运行结果如下:

hello

UnixDatagram 的使用

from std import socket.*
from std import time.*
from std import sync.*
from std import fs.*
from std import os.*
from std import random.*

func createTempFile(): String {
    let tempDir: Path = tempDir().info.path

    let index: String = Random().nextUInt64().toString()

    return tempDir.join("tmp${index}").toString()
}

func runUnixDatagramServer(serverPath: String, clientPath: String) {
    try (serverSocket = UnixDatagramSocket(bindAt: serverPath)) {
        serverSocket.bind()

        let buf = Array<Byte>(3, item: 0)

        let (clientAddr, read) = serverSocket.receiveFrom(buf)

        if (read == 3 && buf == Array<Byte>([1, 2, 3])) {
            println("server received")
        }
        if (clientAddr.toString() == clientPath) {
            println("client address correct")
        }
    }
}

main(): Int64 {
    let clientPath = createTempFile()
    let serverPath = createTempFile()
    spawn {
        runUnixDatagramServer(serverPath, clientPath)
    }
    sleep(Duration.second)

    try (unixSocket = UnixDatagramSocket(bindAt: clientPath)) {
        unixSocket.sendTimeout = Duration.second * 2
        unixSocket.bind()
        unixSocket.connect(serverPath)

        unixSocket.send(Array<Byte>([1, 2, 3]))
        sleep(Duration.second)
    }

    return 0
}

运行结果如下:

server received
client address correct

增加自定义属性

from std import socket.*

let TCP_KEEPCNT: Int32 = 6

extend TcpSocket {
    public mut prop customNoDelay: Int64 {
        get() {
            Int64(getSocketOptionIntNative(SocketOptions.IPPROTO_TCP, SocketOptions.TCP_NODELAY))
        }
        set(value) {
            setSocketOptionIntNative(SocketOptions.IPPROTO_TCP, SocketOptions.TCP_NODELAY, IntNative(value))
        }
    }
}

main() {
    let socket = TcpSocket("127.0.0.1", 0)
    socket.customNoDelay = 1
    println(socket.customNoDelay)
}

运行结果如下:

属性配置

from std import socket.*
from std import time.*
from std import sync.*

main (){
   try (tcpSocket = TcpSocket("127.0.0.1", 80)) {
      tcpSocket.readTimeout = Duration.second
      tcpSocket.noDelay = false
      tcpSocket.linger = Duration.minute

      tcpSocket.keepAlive = SocketKeepAliveConfig(
         interval: Duration.second * 7,
         count: 15
      )
   }
}

仓颉用户手册