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

Node.js的dgram模塊提供了UDP數(shù)據(jù)報(bào)套接字的實(shí)現(xiàn)。

使用數(shù)據(jù)報(bào)文sockets(Datagram sockets)的方式是調(diào)用require('dgram')。

重要提醒：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'

• exceptionError對(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"）地址(udp4sockets的'0.0.0.0' ，udp6sockets的'::0')

回調(diào)函數(shù)可能用來檢測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é)字符串情況，偏移量和長度是字節(jié)長度byte length，而不是字符串長度。

下面的例子是在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)的最大長度依賴于MTU (Maximum Transmission Unit)和Payload Length的長度。

• 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)

• flagBoolean

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

socket.setTTL(ttl)

• ttl整數(shù)

設(shè)置IP_TTLsocket選項(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ò)探測器或多播。

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

socket.setMulticastTTL(ttl)

• ttl整數(shù)

設(shè)置IP_MULTICAST_TTLsocket選項(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ò)探測器或多播。

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

socket.setMulticastLoopback(flag)

• flag Boolean

設(shè)置或清空IP_MULTICAST_LOOPsocket選項(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_MEMBERSHIPsocket

如果沒有指定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ì)無效。