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


在 socket 上广播一个数据包。 对于无连接的 socket,必须指定目标的 portaddress。 对于连接的 socket,则将会使用其关联的远程端点,因此不能设置 portaddress 参数。

msg 参数包含了要发送的消息。 根据消息的类型可以有不同的做法。 如果 msg 是一个 BufferUint8Array,则 offsetlength 指定了消息在 Buffer 中对应的偏移量和字节数。 如果 msg 是一个String,那么它会被自动地按照 'utf8' 编码转换为 Buffer。 对于包含了多字节字符的消息, offsetlength 会根据对应的字节长度进行计算,而不是根据字符的位置。 如果 msg 是一个数组,那么 offsetlength 必须都不能被指定。

address 参数是一个字符串。 若 address 的值是一个主机名,则 DNS 会被用来解析主机的地址。 若 address 未提供或是非真值,则 '127.0.0.1'(用于 udp4 socket)或 '::1'(用于 udp6 socket)会被使用。

若在之前 socket 未通过调用 bind 方法进行绑定,socket 将会被一个随机的端口号赋值并绑定到“所有接口”的地址上(对于 udp4 socket 是 '0.0.0.0',对于 udp6 socket 是 '::0')。

可以指定一个可选的 callback 方法来汇报 DNS 错误或判断可以安全地重用 buf 对象的时机。 在 Node.js 事件循环中,DNS 查询会对发送造成至少一个时间点的延迟。

确定数据包被发送的唯一方式就是指定 callback。 若在 callback 被指定的情况下有错误发生,该错误会作为 callback 的第一个参数。 若 callback 未被指定,该错误会以 'error' 事件的方式投射到 socket 对象上。

偏移量和长度是可选的,但如其中一个被指定则另一个也必须被指定。 另外,它们只在第一个参数是 BufferUint8Array 的情况下才能被使用。

示例,发送 UDP 包到 localhost 上的某个端口:

const dgram = require('dgram');
const message = Buffer.from('一些字节');
const client = dgram.createSocket('udp4');
client.send(message, 41234, 'localhost', (err) => {
  client.close();
});

示例,发送包含多个 buffer 的 UDP 包到 127.0.0.1 上的某个端口:

const dgram = require('dgram');
const buf1 = Buffer.from('一些 ');
const buf2 = Buffer.from('字节');
const client = dgram.createSocket('udp4');
client.send([buf1, buf2], 41234, (err) => {
  client.close();
});

发送多个 buffer 的速度取决于应用和操作系统。 逐案运行基准来确定最佳策略。 但是一般来说,发送多个 buffer 速度更快。

示例,使用已连接的 socket 发送 UDP 包到 localhost 上的某个端口:

const dgram = require('dgram');
const message = Buffer.from('一些字节');
const client = dgram.createSocket('udp4');
client.connect(41234, 'localhost', (err) => {
  client.send(message, (err) => {
    client.close();
  });
});

Broadcasts a datagram on the socket. For connectionless sockets, the destination port and address must be specified. Connected sockets, on the other hand, will use their associated remote endpoint, so the port and address arguments must not be set.

The msg argument contains the message to be sent. Depending on its type, different behavior can apply. If msg is a Buffer or Uint8Array, the offset and length specify the offset within the Buffer where the message begins and the number of bytes in the message, respectively. If msg is a String, then it is automatically converted to a Buffer with 'utf8' encoding. With messages that contain multi-byte characters, offset and length will be calculated with respect to byte length and not the character position. If msg is an array, offset and length must not be specified.

The address argument is a string. If the value of address is a host name, DNS will be used to resolve the address of the host. If address is not provided or otherwise falsy, '127.0.0.1' (for udp4 sockets) or '::1' (for udp6 sockets) will be used by default.

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

An optional callback function may be specified to as a way of reporting DNS errors or for determining when it is safe to reuse the buf object. DNS lookups delay the time to send for at least one tick of the Node.js event loop.

The only way to know for sure that the datagram has been sent is by using a callback. If an error occurs and a callback is given, the error will be passed as the first argument to the callback. If a callback is not given, the error is emitted as an 'error' event on the socket object.

Offset and length are optional but both must be set if either are used. They are supported only when the first argument is a Buffer or Uint8Array.

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

const dgram = require('dgram');
const message = Buffer.from('Some bytes');
const client = dgram.createSocket('udp4');
client.send(message, 41234, 'localhost', (err) => {
  client.close();
});

Example of sending a UDP packet composed of multiple buffers to a port on 127.0.0.1;

const dgram = require('dgram');
const buf1 = Buffer.from('Some ');
const buf2 = Buffer.from('bytes');
const client = dgram.createSocket('udp4');
client.send([buf1, buf2], 41234, (err) => {
  client.close();
});

Sending multiple buffers might be faster or slower depending on the application and operating system. Run benchmarks to determine the optimal strategy on a case-by-case basis. Generally speaking, however, sending multiple buffers is faster.

Example of sending a UDP packet using a socket connected to a port on localhost:

const dgram = require('dgram');
const message = Buffer.from('Some bytes');
const client = dgram.createSocket('udp4');
client.connect(41234, 'localhost', (err) => {
  client.send(message, (err) => {
    client.close();
  });
});