本作品采用知识共享署名-非商业性使用 3.0 未本地化版本许可协议进行许可。

目录

• UDP / 数据报套接字
  • dgram.createSocket(type, [callback])
  • 类: dgram.Socket
    • 事件: 'message'
    • 事件: 'listening'
    • 事件: 'close'
    • 事件: 'error'
    • socket.send(buf, offset, length, port, address, [callback])
    • socket.bind(port, [address], [callback])
    • socket.close()
    • socket.address()
    • socket.setBroadcast(flag)
    • socket.setTTL(ttl)
    • socket.setMulticastTTL(ttl)
    • socket.setMulticastLoopback(flag)
    • socket.addMembership(multicastAddress, [multicastInterface])
    • socket.dropMembership(multicastAddress, [multicastInterface])
    • socket.unref()
    • socket.ref()

UDP / 数据报套接字#

稳定度: 3 - 稳定

Datagram sockets are available through require('dgram').

数据报套接字通过 require('dgram') 提供。

Important note: the behavior of dgram.Socket#bind() has changed in v0.10 and is always asynchronous now. If you have code that looks like this:

重要提醒：dgram.Socket#bind() 的行为在 v0.10 中已改变，并且现在它总是异步的。如果您的代码看起来像这样：

var s = dgram.createSocket('udp4');
s.bind(1234);
s.addMembership('224.0.0.114');

You have to change it to this:

您需要将它改成这样：

var s = dgram.createSocket('udp4');
s.bind(1234, function() {
  s.addMembership('224.0.0.114');
});

dgram.createSocket(type, [callback])#

Creates a datagram Socket of the specified types. Valid types are udp4 and udp6.

创建一个指定类型的数据报 Socket。有效类型包括 udp4 和 udp6。

Takes an optional callback which is added as a listener for message events.

接受一个可选的回调，会被添加为 message 事件的监听器。

Call socket.bind if you want to receive datagrams. socket.bind() will bind to the "all interfaces" address on a random port (it does the right thing for both udp4 and udp6 sockets). You can then retrieve the address and port with socket.address().address and socket.address().port.

如果您想接收数据报则可调用 socket.bind。socket.bind() 会绑定到“所有网络接口”地址的一个随机端口（udp4 和 udp6 皆是如此）。然后您可以通过 socket.address().address 和 socket.address().port 来取得地址和端口。

类: dgram.Socket#

The dgram Socket class encapsulates the datagram functionality. It should be created via dgram.createSocket(type, [callback]).

dgram Socket 类封装了数据报功能，可以通过 dgram.createSocket(type, [callback]) 创建。

事件: 'message'#

Emitted when a new datagram is available on a socket. msg is a Buffer and rinfo is an object with the sender's address information:

当套接字中有新的数据报时发生。msg 是一个 Buffer，rinfo 是一个包含了发送者地址信息的对象：

socket.on('message', function(msg, rinfo) {
  console.log('收到 %d 字节，来自 %s:%d\n',
              msg.length, rinfo.address, rinfo.port);
});

事件: 'listening'#

Emitted when a socket starts listening for datagrams. This happens as soon as UDP sockets are created.

当一个套接字开始监听数据报时产生。它会在 UDP 套接字被创建时发生。

事件: 'close'#

Emitted when a socket is closed with close(). No new message events will be emitted on this socket.

当一个套接字被 close() 关闭时产生。之后这个套接字上不会再有 message 事件发生。

事件: 'error'#

Emitted when an error occurs.

当发生错误时产生。

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

For UDP sockets, the destination port and IP address must be specified. A string may be supplied for the address parameter, and it will be resolved with DNS. An optional callback may be specified to detect any DNS errors and when buf may be re-used. Note that DNS lookups will delay the time that a send takes place, at least until the next tick. The only way to know for sure that a send has taken place is to use the callback.

对于 UDP 套接字，必须指定目标端口和 IP 地址。address 参数可以是一个字符串，它会被 DNS 解析。可选地可以指定一个回调以用于发现任何 DNS 错误或当 buf 可被重用。请注意 DNS 查询会将发送的时间推迟到至少下一个事件循环。确认发送完毕的唯一已知方法是使用回调。

If the socket has not been previously bound with a call to bind, it's assigned a random port number and bound to the "all interfaces" address (0.0.0.0 for udp4 sockets, ::0 for udp6 sockets).

如果套接字之前并未被调用 bind 绑定，则它会被分配一个随机端口并绑定到“所有网络接口”地址（udp4 套接字是 0.0.0.0；udp6 套接字是 ::0）。

Example of sending a UDP packet to a random port on localhost;

向 localhost 随机端口发送 UDP 报文的例子：

var dgram = require('dgram');
var message = new Buffer("Some bytes");
var client = dgram.createSocket("udp4");
client.send(message, 0, message.length, 41234, "localhost", function(err) {
  client.close();
});

A Note about UDP datagram size

关于 UDP 数据报大小的注意事项

The maximum size of an IPv4/v6 datagram depends on the MTU (Maximum Transmission Unit) and on the Payload Length field size.

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

• The Payload Length field is 16 bits wide, which means that a normal payload cannot be larger than 64K octets including internet header and data (65,507 bytes = 65,535 − 8 bytes UDP header − 20 bytes IP header); this is generally true for loopback interfaces, but such long datagrams are impractical for most hosts and networks.

• Payload Length 字段宽 16 bits，意味着正常负载包括网络头和数据不能大于 64K（65,507 字节 = 65,535 − 8 字节 UDP 头 − 20 字节 IP 头）；这对环回接口通常是真的，但如此大的数据报对大多数主机和网络来说是不切实际的。

• The MTU is the largest size a given link layer technology can support for datagrams. For any link, IPv4 mandates a minimum MTU of 68 octets, while the recommended MTU for IPv4 is 576 (typically recommended as the MTU for dial-up type applications), whether they arrive whole or in fragments.

• MTU 是一个给定的数据链路层技术能为数据报提供支持的最大大小。对于任何连接，IPv4 允许最小 68 字节的 MTU，而 IPv4 所推荐的 MTU 为 576（通常作为拨号类应用的推荐 MTU），无论它们是完整接收还是分片。

  For IPv6, the minimum MTU is 1280 octets, however, the mandatory minimum fragment reassembly buffer size is 1500 octets. The value of 68 octets is very small, since most current link layer technologies have a minimum MTU of 1500 (like Ethernet).

  对于 IPv6，最小的 MTU 为 1280 字节，但所允许的最小碎片重组缓冲大小为 1500 字节。 68 的值是非常小的，因为现在大多数数据链路层技术有都具有 1500 的最小 MTU（比如以太网）。

Note that it's impossible to know in advance the MTU of each link through which a packet might travel, and that generally sending a datagram greater than the (receiver) MTU won't work (the packet gets silently dropped, without informing the source that the data did not reach its intended recipient).

请注意我们不可能提前得知一个报文可能经过的每一个连接 MTU，因此通常情况下不能发送一个大于（接收者的）MTU 的数据报（报文会被悄悄地丢掉，而不会将数据没有到达它意图的接收者的消息告知来源）。

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

For UDP sockets, listen for datagrams on a named port and optional address. If address is not specified, the OS will try to listen on all addresses. After binding is done, a "listening" event is emitted and the callback(if specified) is called. Specifying both a "listening" event listener and callback is not harmful but not very useful.

对于 UDP 套接字，在一个具名端口 port 和可选的地址 address 上监听数据报。如果 address 未指定，则操作系统会尝试监听所有地址。当绑定完成后，一个 "listening" 事件会发生，并且回调 callback（如果指定）会被调用。同时指定 "listening" 事件监听器和 callback 并不会产生副作用，但也没什么用。

A bound datagram socket keeps the node process running to receive datagrams.

一个绑定了的数据报套接字会保持 node 进程运行来接收数据报。

If binding fails, an "error" event is generated. In rare case (e.g. binding a closed socket), an Error may be thrown by this method.

如果绑定失败，则一个 "error" 事件会被产生。在极少情况下（比如绑定一个已关闭的套接字），该方法会抛出一个 Error。

Example of a UDP server listening on port 41234:

一个监听端口 41234 的 UDP 服务器的例子：

server.bind(41234);
// 服务器正在监听 0.0.0.0:41234

socket.close()#

Close the underlying socket and stop listening for data on it.

关闭底层套接字并停止监听数据。

socket.address()#

Returns an object containing the address information for a socket. For UDP sockets, this object will contain address , family and port.

返回一个包含了套接字地址信息的对象。对于 UDP 套接字，该对象会包含地址 address、地址族 family 和端口号 port。

socket.setBroadcast(flag)#

Sets or clears the SO_BROADCAST socket option. When this option is set, UDP packets may be sent to a local interface's broadcast address.

设置或清除 SO_BROADCAST 套接字选项。当该选项被设置，则 UDP 报文可能被发送到一个本地接口的广播地址。

socket.setTTL(ttl)#

Sets the IP_TTL socket option. TTL stands for "Time to Live," but in this context it specifies the number of IP hops that a packet is allowed to go through. Each router or gateway that forwards a packet decrements the TTL. If the TTL is decremented to 0 by a router, it will not be forwarded. Changing TTL values is typically done for network probes or when multicasting.

设置 IP_TTL 套接字选项。TTL 表示“Time to Live”（生存时间），但在此上下文中它指的是报文允许通过的 IP 跃点数。各个转发报文的路由器或网关都会递减 TTL。如果 TTL 被一个路由器递减到 0，则它将不会被转发。改变 TTL 值通常被用于网络探测器或多播。

The argument to setTTL() is a number of hops between 1 and 255. The default on most systems is 64.

setTTL() 的参数为介于 1 至 255 的跃点数。在大多数系统上缺省值为 64。

socket.setMulticastTTL(ttl)#

Sets the IP_MULTICAST_TTL socket option. TTL stands for "Time to Live," but in this context it specifies the number of IP hops that a packet is allowed to go through, specifically for multicast traffic. Each router or gateway that forwards a packet decrements the TTL. If the TTL is decremented to 0 by a router, it will not be forwarded.

设置 IP_MULTICAST_TTL 套接字选项。TTL 表示“Time to Live”（生存时间），但在此上下文中它指的是报文允许通过的 IP 跃点数，特别是组播流量。各个转发报文的路由器或网关都会递减 TTL。如果 TTL 被一个路由器递减到 0，则它将不会被转发。

The argument to setMulticastTTL() is a number of hops between 0 and 255. The default on most systems is 1.

setMulticastTTL() 的参数为介于 1 至 255 的跃点数。在大多数系统上缺省值为 1。

socket.setMulticastLoopback(flag)#

Sets or clears the IP_MULTICAST_LOOP socket option. When this option is set, multicast packets will also be received on the local interface.

设置或清除 IP_MULTICAST_LOOP 套接字选项。当该选项被设置时，组播报文也会被本地接口收到。

socket.addMembership(multicastAddress, [multicastInterface])#

Tells the kernel to join a multicast group with IP_ADD_MEMBERSHIP socket option.

以 IP_ADD_MEMBERSHIP 套接字选项告诉内核加入一个组播分组。

If multicastInterface is not specified, the OS will try to add membership to all valid interfaces.

如果未指定 multicastInterface，则操作系统会尝试向所有有效接口添加关系。

socket.dropMembership(multicastAddress, [multicastInterface])#

Opposite of addMembership - tells the kernel to leave a multicast group with IP_DROP_MEMBERSHIP socket option. This is automatically called by the kernel when the socket is closed or process terminates, so most apps will never need to call this.

与 addMembership 相反，以 IP_DROP_MEMBERSHIP 套接字选项告诉内核退出一个组播分组。当套接字被关闭或进程结束时内核会自动调用，因此大多数应用都没必要调用它。

If multicastInterface is not specified, the OS will try to drop membership to all valid interfaces.

如果未指定 multicastInterface，则操作系统会尝试向所有有效接口移除关系。

socket.unref()#

Calling unref on a socket will allow the program to exit if this is the only active socket in the event system. If the socket is already unrefd calling unref again will have no effect.

如果这是事件系统中唯一一个活动的套接字，调用 unref 将允许程序退出。如果套接字已被 unref，则再次调用 unref 并不会产生影响。

socket.ref()#

Opposite of unref, calling ref on a previously unrefd socket will not let the program exit if it's the only socket left (the default behavior). If the socket is refd calling ref again will have no effect.

与 unref 相反，如果这是仅剩的套接字，在一个之前被 unref 了的套接字上调用 ref 将不会让程序退出（缺省行为）。如果一个套接字已经被 ref，则再次调用 ref 并不会产生影响。