Node.js v14.20.0 文档

dgram.Socket 类#

中英对照

封装数据报功能。

'close' 事件#

中英对照

在使用 close() 关闭套接字后会触发 'close' 事件。 一旦触发，则此套接字上将不会触发新的 'message' 事件。

'connect' 事件#

中英对照

'connect' 事件在套接字关联到远程地址作为成功的 connect() 调用的结果之后触发。

'error' 事件#

中英对照

每当发生任何错误时都会触发 'error' 事件。 事件句柄被传入单一的 Error 对象。

'listening' 事件#

中英对照

一旦 dgram.Socket 可寻址并且可以接收数据，则会触发 'listening' 事件。 这会在 socket.bind() 中显式地发生，或者在第一次使用 socket.send() 发送数据时隐式地发生。 直到 dgram.Socket 正在监听，底层系统资源不存在，则调用 socket.address() 和 socket.setTTL() 等将失败。

'message' 事件#

中英对照

当套接字上有新的数据报可用时，则会触发 'message' 事件。 事件句柄传入了两个参数：msg 和 rinfo。

socket.addMembership(multicastAddress[, multicastInterface])#

中英对照

使用 IP_ADD_MEMBERSHIP 套接字选项告诉内核在给定的 multicastAddress 和 multicastInterface 上加入多播组。 如果未指定 multicastInterface 参数，则操作系统将选择一个接口并为其添加成员资格。 要为每个可用接口添加成员资格，则多次调用 addMembership，每个接口一次。

socket.addSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])#

中英对照

告诉内核在给定的 sourceAddress 和 groupAddress 上加入特定于源的多播频道，使用 multicastInterface 和 IP_ADD_SOURCE_MEMBERSHIP 套接字选项。 如果未指定 multicastInterface 参数，则操作系统将选择一个接口并为其添加成员资格。 要为每个可用接口添加成员资格，则多次调用 socket.addSourceSpecificMembership()，每个接口一次。

socket.address()#

中英对照

返回包含套接字地址信息的对象。 对于 UDP 套接字，此对象将包含 address、family 和 port 属性。

socket.bind([port][, address][, callback])#

中英对照

对于 UDP 套接字，使 dgram.Socket 在命名的 port 和可选的 address 上监听数据报消息。 如果未指定 port 或 0，则操作系统将尝试绑定到随机端口。 如果未指定 address，则操作系统将尝试监听所有地址。 一旦绑定完成，则会触发 'listening' 事件并调用可选的 callback 函数。

socket.bind(options[, callback])#

中英对照

对于 UDP 套接字，使 dgram.Socket 监听命名 port 和可选 address 上的数据报消息，这些消息作为作为第一个参数传入的 options 对象的属性传入。 如果未指定 port 或 0，则操作系统将尝试绑定到随机端口。 如果未指定 address，则操作系统将尝试监听所有地址。 一旦绑定完成，则会触发 'listening' 事件并调用可选的 callback 函数。

socket.close([callback])#

中英对照

关闭底层套接字并停止监听其上的数据。 如果提供回调，则将其添加为 'close' 事件的监听器。

socket.connect(port[, address][, callback])#

中英对照

将 dgram.Socket 关联到远程地址和端口。 此句柄发送的每条消息都会自动发送到该目标。 此外，套接字将只接收来自该远程对等方的消息。 尝试在已连接的套接字上调用 connect() 将导致 ERR_SOCKET_DGRAM_IS_CONNECTED 异常。 如果未提供 address，则默认使用 '127.0.0.1'（适用于 udp4 套接字）或 '::1'（适用于 udp6 套接字）。 一旦连接完成，就会触发 'connect' 事件并调用可选的 callback 函数。 如果失败，则调用 callback，或者触发 'error' 事件。

socket.disconnect()#

中英对照

将连接的 dgram.Socket 与其远程地址分离的同步函数。 尝试在未绑定或已断开连接的套接字上调用 disconnect() 将导致 ERR_SOCKET_DGRAM_NOT_CONNECTED 异常。

socket.dropMembership(multicastAddress[, multicastInterface])#

中英对照

指示内核使用 IP_DROP_MEMBERSHIP 套接字选项离开 multicastAddress 处的多播组。 当套接字关闭或进程终止时，内核会自动调用此方法，因此大多数应用程序永远没有理由调用此方法。

socket.dropSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])#

中英对照

指示内核使用 IP_DROP_SOURCE_MEMBERSHIP 套接字选项在给定的 sourceAddress 和 groupAddress 处保留特定于源的多播通道。 当套接字关闭或进程终止时，内核会自动调用此方法，因此大多数应用程序永远没有理由调用此方法。

socket.getRecvBufferSize()#

中英对照

如果在未绑定的套接字上调用此方法将抛出 ERR_SOCKET_BUFFER_SIZE。

socket.getSendBufferSize()#

中英对照

如果在未绑定的套接字上调用此方法将抛出 ERR_SOCKET_BUFFER_SIZE。

socket.ref()#

中英对照

默认情况下，只要套接字处于打开状态，则绑定套接字将导致它阻止 Node.js 进程退出。 socket.unref() 方法可用于从保持 Node.js 进程处于活动状态的引用计数中排除套接字。 socket.ref() 方法将套接字添加回引用计数并恢复默认行为。

socket.remoteAddress()#

中英对照

返回包含远程端点的 address、family 和 port 的对象。 如果套接字未连接，则此方法将抛出 ERR_SOCKET_DGRAM_NOT_CONNECTED 异常。

socket.send(msg[, offset, length][, port][, address][, callback])#

中英对照

在套接字上广播数据报。 对于无连接套接字，则必须指定目标 port 和 address。 另一方面，已连接的套接字将使用其关联的远程端点，因此不得设置 port 和 address 参数。

关于 UDP 数据报大小的说明#

中英对照

IPv4/v6 数据报的最大大小取决于 MTU（最大传输单元）和 Payload Length 字段大小。

socket.setBroadcast(flag)#

中英对照

设置或清除 SO_BROADCAST 套接字选项。 当设置为 true 时，UDP 数据包可能会被发送到本地接口的广播地址。

socket.setMulticastInterface(multicastInterface)#

中英对照

本节中对范围的所有引用均指 IPv6 区域索引，由 RFC 4007 定义。 以字符串形式，具有作用域索引的 IP 写成 'IP%scope'，其中作用域是接口名称或接口编号。

IPv6 发送多播数据包#

中英对照

在大多数系统上，范围格式使用接口名称：

IPv4 发送多播数据包#

中英对照

所有系统都在所需的物理接口上使用主机的 IP：

调用的结果#

中英对照

对未准备好发送或不再打开的套接字的调用可能会抛出 Not running Error。

socket.setMulticastLoopback(flag)#

中英对照

设置或清除 IP_MULTICAST_LOOP 套接字选项。 当设置为 true 时，本地接口也会收到多播数据包。

socket.setMulticastTTL(ttl)#

中英对照

设置 IP_MULTICAST_TTL 套接字选项。 虽然 TTL 通常代表 "生存时间"，但在此上下文中，它指定了允许数据包通过的 IP 跃点数，特别是对于多播流量。 转发数据包的每个路由器或网关都会递减 TTL。 如果 TTL 被路由器递减为 0，则不会转发。

socket.setRecvBufferSize(size)#

中英对照

设置 SO_RCVBUF 套接字选项。 设置最大套接字接收缓冲区（以字节为单位）。

socket.setSendBufferSize(size)#

中英对照

设置 SO_SNDBUF 套接字选项。 设置最大套接字发送缓冲区（以字节为单位）。

socket.setTTL(ttl)#

中英对照

设置 IP_TTL 套接字选项。 虽然 TTL 通常代表"生存时间"，但在此上下文中，它指定了允许数据包通过的 IP 跃点数。 转发数据包的每个路由器或网关都会递减 TTL。 如果 TTL 被路由器递减为 0，则不会转发。 更改 TTL 值通常用于网络探测或多播。

socket.unref()#

中英对照

默认情况下，只要套接字处于打开状态，则绑定套接字将导致它阻止 Node.js 进程退出。 socket.unref() 方法可用于将套接字从保持 Node.js 进程处于活动状态的引用计数中排除，即使套接字仍在监听，也允许进程退出。

dgram 模块的函数#

dgram.createSocket(options[, callback])#

中英对照

创建 dgram.Socket 对象。 一旦创建了套接字，则调用 socket.bind() 将指示套接字开始监听数据报消息。 当 address 和 port 没有传给 socket.bind() 时，则该方法会将套接字绑定到随机端口上的“所有接口”地址（它对 udp4 和 udp6 套接字都做正确的事情）。 可以使用 socket.address().address 和 socket.address().port 检索绑定的地址和端口。

dgram.createSocket(type[, callback])#

中英对照

创建指定 type 的 dgram.Socket 对象。