穩(wěn)定性: 3 - 穩(wěn)定

調(diào)用 require('dgram') ，可以使用數(shù)據(jù)報(bào)文 sockets(Datagram sockets)。

重要提醒： dgram.Socket#bind() 的行為在 v0.10 做了改動(dòng) ，它總是異步的。如果你的代碼像下面的一樣：

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

現(xiàn)在需要改為：

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

dgram.createSocket(type[, callback])

• type 字符串. 'udp4' 或 'udp6'
• callback 函數(shù). 附加到 message 事件的監(jiān)聽器?？蛇x參數(shù)。
• 返回: Socket 對(duì)象

創(chuàng)建指定類型的數(shù)據(jù)報(bào)文(datagram) Socket。有效類型是udp4 和 udp6

接受一個(gè)可選的回調(diào)，會(huì)被添加為 message 的監(jiān)聽事件。

如果你想接收數(shù)據(jù)報(bào)文(datagram)可以調(diào)用 socket.bind()。socket.bind() 將會(huì)綁定到所有接口（"all interfaces"）的隨機(jī)端口上（ udp4 和 udp6 sockets 都適用）。你可以通過socket.address().address 和 socket.address().port 獲取地址和端口。

dgram.createSocket(options[, callback])

• options 對(duì)象
• callback 函數(shù). 給 message 事件添加事件監(jiān)聽器.
• 返回: Socket 對(duì)象

參數(shù) options 必須包含 type 值(udp4 或 udp6),或可選的 boolean 值 reuseAddr。

當(dāng) reuseAddr 為 true 時(shí)， socket.bind() 將會(huì)重用地址，即使另一個(gè)進(jìn)程已經(jīng)綁定 socket。 reuseAddr 默認(rèn)為 false。

回調(diào)函數(shù)為可選參數(shù)，作為 message 事件的監(jiān)聽器。

如果你想接受數(shù)據(jù)報(bào)文(datagram)，可以調(diào)用 socket.bind() 。socket.bind() 將會(huì)綁定到所有接口（ "all interfaces" ）地址的隨機(jī)端口上（ udp4 和 udp6 sockets 都適用）。你可以通過socket.address().address 和 socket.address().port 獲取地址和端口。

Class: dgram.Socket

報(bào)文數(shù)據(jù) Socket 類封裝了數(shù)據(jù)報(bào)文(datagram) 函數(shù)。必須通過 dgram.createSocket(...) 函數(shù)創(chuàng)建。

Event: 'message'

• msg 緩存對(duì)象. 消息。
• rinfo 對(duì)象. 遠(yuǎn)程地址信息。

當(dāng) socket 上新的數(shù)據(jù)報(bào)文(datagram)可用的時(shí)候，會(huì)觸發(fā)這個(gè)事件。msg 是一個(gè)緩存，rinfo 是一個(gè)包含發(fā)送者地址信息的對(duì)象

socket.on('message', function(msg, rinfo) {
  console.log('Received %d bytes from %s:%d\n',
              msg.length, rinfo.address, rinfo.port);
});

Event: 'listening'

當(dāng) socket 開始監(jiān)聽數(shù)據(jù)報(bào)文(datagram)時(shí)觸發(fā)。在 UDP socket 創(chuàng)建時(shí)觸發(fā)。

Event: 'close'

當(dāng) socket 使用 close() 關(guān)閉時(shí)觸發(fā)。在這個(gè) socket 上不會(huì)觸發(fā)新的消息事件。

Event: 'error'

• exception Error 對(duì)象

當(dāng)發(fā)生錯(cuò)誤時(shí)觸發(fā)。

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

• buf 緩存對(duì)象 或 字符串. 要發(fā)送的消息。
• offset 整數(shù). 消息在緩存中得偏移量。
• length 整數(shù). 消息的比特?cái)?shù)。
• port 整數(shù). 端口的描述。
• address 字符串. 目標(biāo)的主機(jī)名或 IP 地址。
• callback 函數(shù). 當(dāng)消息發(fā)送完畢的時(shí)候調(diào)用?？蛇x。

對(duì)于 UDP socket，必須指定目標(biāo)端口和地址。 address 參數(shù)可能是字符串，它會(huì)被 DNS 解析。

如果忽略地址或者地址是空字符串，將使用 '0.0.0.0' 或 '::0' 替代。依賴于網(wǎng)絡(luò)配置，這些默認(rèn)值有可能行也可能不行。

如果 socket 之前沒被調(diào)用 bind 綁定，則它會(huì)被分配一個(gè)隨機(jī)端口并綁定到所有接口（ "all interfaces" ）地址(udp4 sockets 的'0.0.0.0' , udp6 sockets 的'::0')

回調(diào)函數(shù)可能用來檢測(cè) DNS 錯(cuò)誤，或用來確定什么時(shí)候重用 buf 對(duì)象。注意，DNS 查詢會(huì)導(dǎo)致發(fā)送tick延遲。通過回調(diào)函數(shù)能確認(rèn)數(shù)據(jù)報(bào)文(datagram)是否已經(jīng)發(fā)送的

考慮到多字節(jié)字符串情況，偏移量和長(zhǎng)度是字節(jié)長(zhǎng)度byte length，而不是字符串長(zhǎng)度。

下面的例子是在 localhost 上發(fā)送一個(gè) UDP 包給隨機(jī)端口：

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();
});

關(guān)于 UDP 數(shù)據(jù)報(bào)文(datagram) 尺寸

IPv4/v6 數(shù)據(jù)報(bào)文(datagram)的最大長(zhǎng)度依賴于MTU (Maximum Transmission Unit)和 Payload Length 的長(zhǎng)度。

• Payload Length 內(nèi)容為 16 位寬，它意味著 Payload 的最大字節(jié)說不超過 64k，其中包括了頭信息和數(shù)據(jù)（65,507 字節(jié) = 65,535 ? 8 字節(jié) UDP 頭 ? 20 字節(jié) IP 頭）;對(duì)于環(huán)回接口（loopback interfaces）這是真的，但對(duì)于多數(shù)主機(jī)和網(wǎng)絡(luò)來說不太現(xiàn)實(shí)。

• MTU 能支持?jǐn)?shù)據(jù)報(bào)文(datagram)的最大值（以目前鏈路層技術(shù)來說）。對(duì)于任何連接，IPv4 允許的最小值為 68 的 MTU，推薦值為 576 （通常推薦作撥號(hào)應(yīng)用的 MTU）,無論他們是完整接收還是碎片接收。

  對(duì)于 IPv6，MTU 的最小值為 1280 字節(jié)，最小碎片緩存大小為 1500 字節(jié)。16 字節(jié)實(shí)在是太小，所以目前鏈路層一般最小 MTU 大小為 1500。

我們不可能知道一個(gè)包可能進(jìn)過的每個(gè)連接的MTU。通常發(fā)送一個(gè)超過接收端 MTU 大小的數(shù)據(jù)報(bào)文(datagram)會(huì)失效。（數(shù)據(jù)包會(huì)被悄悄的拋棄，不會(huì)通知發(fā)送端數(shù)據(jù)包沒有到達(dá)接收端）。

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

• port 整數(shù)
• address 字符串, 可選
• callback 沒有參數(shù)的函數(shù), 可選。綁定時(shí)會(huì)調(diào)用回調(diào)。

對(duì)于 UDP socket，在一個(gè)端口和可選地址上監(jiān)聽數(shù)據(jù)報(bào)文(datagram)。如果沒有指定地點(diǎn)，系統(tǒng)將會(huì)參數(shù)監(jiān)聽所有的地址。綁定完畢后，會(huì)觸發(fā) "listening" 事件，并會(huì)調(diào)用傳入的回調(diào)函數(shù)。指定監(jiān)聽事件和回調(diào)函數(shù)非常有用。

一個(gè)綁定了的數(shù)據(jù)報(bào)文 socket 會(huì)保持 node 進(jìn)程運(yùn)行來接收數(shù)據(jù)。

如果綁定失敗，會(huì)產(chǎn)生錯(cuò)誤事件。極少數(shù)情況（比如綁定一個(gè)關(guān)閉的 socket）。這個(gè)方法會(huì)拋出一個(gè)錯(cuò)誤。

以下是 UDP 服務(wù)器監(jiān)聽端口 41234 的例子：

var dgram = require("dgram");

var server = dgram.createSocket("udp4");

server.on("error", function (err) {
  console.log("server error:\n" + err.stack);
  server.close();
});

server.on("message", function (msg, rinfo) {
  console.log("server got: " + msg + " from " +
    rinfo.address + ":" + rinfo.port);
});

server.on("listening", function () {
  var address = server.address();
  console.log("server listening " +
      address.address + ":" + address.port);
});

server.bind(41234);
// server listening 0.0.0.0:41234

socket.bind(options[, callback])

• options {對(duì)象} - 必需. 有以下的屬性:
  • port {Number} - 必需.
  • address {字符串} - 可選.
  • exclusive {Boolean} - 可選.
• callback {函數(shù)} - 可選.

options 的可選參數(shù)port 和 address，以及可選參數(shù) callback，好像在調(diào)用 socket.bind(port, [address], [callback]) 。

如果 exclusive 是 false （默認(rèn)），集群進(jìn)程將會(huì)使用相同的底層句柄，允許連接處理共享的任務(wù)。當(dāng)exclusive 為 true 時(shí)，句柄不會(huì)共享，嘗試共享端口也會(huì)失敗。監(jiān)聽 exclusive 端口的例子如下：

socket.bind({
  address: 'localhost',
  port: 8000,
  exclusive: true
});

socket.close()

關(guān)閉底層 socket 并且停止監(jiān)聽數(shù)據(jù)。

socket.address()

返回一個(gè)包含套接字地址信息的對(duì)象。對(duì)于 UDP socket，這個(gè)對(duì)象會(huì)包含address , family 和 port。

socket.setBroadcast(flag)

• flag Boolean

設(shè)置或清除 SO_BROADCAST socket 選項(xiàng)。設(shè)置這個(gè)選項(xiàng)后，UDP 包可能會(huì)發(fā)送給一個(gè)本地的接口廣播地址。

socket.setTTL(ttl)

• ttl 整數(shù)

設(shè)置 IP_TTL socket 選項(xiàng)。 TTL 表示生存時(shí)間（Time to Live），但是在這個(gè)上下文中它指的是報(bào)文允許通過的 IP 躍點(diǎn)數(shù)。各個(gè)轉(zhuǎn)發(fā)報(bào)文的路由器或者網(wǎng)關(guān)都會(huì)遞減 TTL。如果 TTL 被路由器遞減為0，則它將不會(huì)被轉(zhuǎn)發(fā)。改變 TTL 的值通常用于網(wǎng)絡(luò)探測(cè)器或多播。

setTTL() 的參數(shù)為 1 到 255 的躍點(diǎn)數(shù)。多數(shù)系統(tǒng)默認(rèn)值為 64.

socket.setMulticastTTL(ttl)

• ttl 整數(shù)

設(shè)置 IP_MULTICAST_TTL socket 選項(xiàng). TTL 表示生存時(shí)間（Time to Live），但是在這個(gè)上下文中它指的是報(bào)文允許通過的 IP 躍點(diǎn)數(shù)。 各個(gè)轉(zhuǎn)發(fā)報(bào)文的路由器或者網(wǎng)關(guān)都會(huì)遞減 TTL。如果 TTL 被路由器遞減為0，則它將不會(huì)被轉(zhuǎn)發(fā)。改變 TTL 的值通常用于網(wǎng)絡(luò)探測(cè)器或多播。

setMulticastTTL() 的參數(shù)為 1 到 255 的躍點(diǎn)數(shù)。多數(shù)系統(tǒng)默認(rèn)值為 1.

socket.setMulticastLoopback(flag)

• flag Boolean

設(shè)置或清空 IP_MULTICAST_LOOP socket 選項(xiàng)。設(shè)置完這個(gè)選項(xiàng)后，當(dāng)該選項(xiàng)被設(shè)置時(shí)，組播報(bào)文也會(huì)被本地接口收到。

socket.addMembership(multicastAddress[, multicastInterface])

• multicastAddress 字符串
• multicastInterface 字符串, 可選

告訴內(nèi)核加入廣播組，選項(xiàng)為 IP_ADD_MEMBERSHIP socket

如果沒有指定 multicastInterface，操作系統(tǒng)會(huì)給所有可用的接口添加關(guān)系。

socket.dropMembership(multicastAddress[, multicastInterface])

• multicastAddress 字符串
• multicastInterface 字符串, 可選

和 addMembership 相反 - 用 IP_DROP_MEMBERSHIP 選項(xiàng)告訴內(nèi)核離開廣播組 。 如果沒有指定 multicastInterface，操作系統(tǒng)會(huì)移除所有可用的接口關(guān)系。

socket.unref()

在 socket 上調(diào)用 unref 允許程序退出，如果這是在事件系統(tǒng)中唯一的活動(dòng) socket。如果 socket 已經(jīng) unref，再次調(diào)用 unref 將會(huì)無效。

socket.ref()

和 unref 相反，如果這是唯一的 socket，在一個(gè)之前被 unref 了的 socket 上調(diào)用 ref 將不會(huì)讓程序退出（缺省行為）。如果一個(gè) socket 已經(jīng)被 ref，則再次調(diào)用 ref 將會(huì)無效。