UDP/Datagram · io.js API 中文文檔

### 穩定度: 2 - 穩定數據報`socket`通過`require('dgram')`使用。重要提示：`dgram.Socket#bind()`的表現在v0.10中被改變，并且現在總是異步的，如果你有像這樣的代碼： ~~~ var s = dgram.createSocket('udp4'); s.bind(1234); s.addMembership('224.0.0.114'); ~~~ 你必須改成這樣： ~~~ var s = dgram.createSocket('udp4'); s.bind(1234, function() { s.addMembership('224.0.0.114'); }); ~~~ #### dgram.createSocket(type[, callback]) - type String. `'udp4'`或`'udp6'`，兩者之一 - callback Function. 可選，會被添加為`message`事件的監聽器 - Returns: `socket`對象創建一個指定類型的數據報`socket`。可用類型是udp4和udp6. 接受一個可選的回調函數，它會被自動添加為`message`事件的監聽器。如果你想要接收數據報，調用`socket.bind()`。`socket.bind()`將會到`所有網絡接口`地址中的一個隨機端口（不論udp4和upd6 `socket`，它都可以正常工作）。你可以從`socket.address().address`和`socket.address().port`中獲取地址和端口。 #### dgram.createSocket(options[, callback]) - options Object - callback Function. 會被添加為`message`事件的監聽器 - Returns: `socket`對象 `options`對象必須包含一個`type`屬性，可是udp4或udp6。還有一個可選的`reuseAddr`布爾值屬性。當`reuseAddr`為`true`時，`socket.bind()`會重用地址，甚至是當另一個進程已經在這之上綁定了一個`socket`時。默認為`false`。接受一個可選的回調函數，它會被自動添加為`message`事件的監聽器。如果你想要接收數據報，調用`socket.bind()`。`socket.bind()`將會到`所有網絡接口`地址中的一個隨機端口（不論udp4和upd6 `socket`，它都可以正常工作）。你可以從`socket.address().address`和`socket.address().port`中獲取地址和端口。 #### Class: dgram.Socket `dgram.Socket`類封裝了數據報的功能。它必須被`dgram.createSocket(...)`創建。 #### Event: 'message' - msg Buffer object. 消息 - rinfo Object. 遠程地址信息當在`socket`中一個新的數據報可用時觸發。`msg`是一個`buffer`并且`rinfo`是一個包含發送者地址信息的對象： ~~~ socket.on('message', function(msg, rinfo) { console.log('Received %d bytes from %s:%d\n', msg.length, rinfo.address, rinfo.port); }); ~~~ #### Event: 'listening' 當一個`socket`開始監聽數據報時觸發。在UDP `socket`被創建時觸發。 #### Event: 'close' 在一個`socket`通過`close()`被關閉時觸發。這個`socket`中不會再觸發新的`message`事件。 #### Event: 'error' - exception Error object 當錯誤發生時觸發。 #### socket.send(buf, offset, length, port, address[, callback]) - buf Buffer object or string. 要被發送的信息。 - offset Integer. 信息在`buffer`里的初始偏移位置。 - length Integer. 信息的字節數。 - port Integer. 目標端口。 - address String. 目標主機或IP地址。 - callback Function. 可選，當信息被發送后調用。對于UDP `socket`，目標端口和地址都必須被指定。`address`參數需要提供一個字符串，并且它會被DNS解析。如果`address`被忽略，或者是一個空字符串。將會使用`'0.0.0.0'`或`'::0'`。這取決于網絡配置，這些默認值可能會或可能不會正常工作；所以最好還是明確指定目標地址。如果一個`socket`先前沒有被調用`bind`來綁定，它將會賦于一個隨機端口數并且被綁定到“所有網絡接口”地址（udp4 `socket`為`'0.0.0.0'`，udp6則為`'::0'`）。一個可選的回調函數可以被指定，用來檢測DNS錯誤，或決定重用`buf`對象是否安全。注意，DNS查找至少會延遲一個事件循環。唯一能確定數據報被發送的方法就是使用一個回調函數。出于對多字節字符的考慮，`offset`和`length`將會根據字節長度而不是字符位置被計算。一個向`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(); }); ~~~ ##### UDP數據報大小的注意事項 IPv4/v6數據報的最大大小取決于`MTU`（最大傳輸單位），和`Payload Length`字段大小。 - `Payload Length`是16字節寬的，意味著一個正常的負載不能超過64K 八位字節，包括網絡頭和數據（65,507 字節 = 65,535 ? 8 字節 UDP 頭 ? 20 字節 IP 頭）；對于環回接口總是`true`，但是如此大的數據報對于大多數主機和網絡來說都是不現實的。 - `MTU`是指定的鏈路層技術支持的報文的最大大小。對于所有連接，IPv4允許最小`MTU`為68八位字節，而推薦的IPv4 `MTU`是576（通常作為撥號類應用的推薦`MTU`），無論它們是完整的還是以碎片形式到達。 - 對于IPv6，最小MTU是1280八位字節，但是，允許的最小`buffer`重組大小是1500八位字節。68八位字節非常小，所以大多數的當前鏈路層技術的最小`MTU`都是1500（如`Ethernet`）。注意，不可能提前知道一個報文可能經過的每一個連接`MTU`，并且通常不能發送一個大于（接收者）`MTU`的數據報（報文會被默默丟棄，不會通知源頭：這個數據沒有到達已定的接收方）。 #### socket.bind(port[, address][, callback]) - port Integer - address String, 可選 - callback Function 可選，沒有參數。當綁定完畢后觸發。對于UDP `socket`，監聽一個具名的端口和一個可選的地址上的數據報。如果`address`沒有被指定，操作系統將會試圖監聽所有端口。在綁定完畢后，`listening`事件會被吃法，并且回調函數（如果指定了）會被調用。同時指定`listening`事件的監聽器和`callback`沒有危險，但是不是很有用。一個綁定的數據報`socket`將會保持`io.js`進程的運行，來接受數據報。如果綁定失敗，一個`error`事件會產生。極少數情況下（例如綁定一個關閉的`socket`），這個方法會拋出一個錯誤。一個監聽41234端口的UDP服務器： ~~~ 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 Object** - 必選，支持以下屬性： - port Number - 必須 - address String - 可選 - exclusive Boolean - 可選 - callback Function - 可選 `options`的`prot`和`address`屬性，以及可選的回調函數，與`socket.bind(port, [address], [callback])`中它們的表現一致。如`exclusive`為`false`（默認），那么集群的工作進程將會使用相同的底層句柄，允許共享處理連接的職責。當為`true`時，句柄不被共享，企圖共享端口會導致一個錯誤。一個監聽一個`exclusive`端口的例子： ~~~ socket.bind({ address: 'localhost', port: 8000, exclusive: true }); ~~~ #### socket.close([callback]) 關閉底層`socket`，并且停止監聽新數據。如果提供了回調函數，它會被添加為`close`事件的監聽器。 #### socket.address() 返回一個包含`socket`地址信息的對象。對于UDP `socket`，這個對象將會包含`address`，`family`和`port`。 #### socket.setBroadcast(flag) - flag Boolean 設置或清除`SO_BROADCAST``socket`設置。當這個選項被設置，UDP報文將會被送至本地接口的廣播地址。 #### socket.setTTL(ttl) - ttl Integer 設置`IP_TTL``socket`選項。`TTL`的意思是“生存時間（Time to Live）”，但是在這里的上下文中，它值一個報文通過的IP躍點數。每轉發報文的路由或網關都會遞減`TTL`。如果`TTL`被一個路由遞減為`0`，它將不再被轉發。改變`TTL`值常用于網絡探測器或多播。 `setTTL()`的參數是一個`1`到`225`之間的躍點數。多數系統中的默認值為`64`。 #### socket.setMulticastTTL(ttl) - ttl Integer 設置`IP_MULTICAST_TTL``socket`選項。`TTL`的意思是“生存時間（Time to Live）”，但是在這里的上下文中，它值一個報文通過的IP躍點數，特別是組播流量。每轉發報文的路由或網關都會遞減`TTL`。如果`TTL`被一個路由遞減為`0`，它將不再被轉發。 `setMulticastTTL()`的參數是一個`0`到`225`之間的躍點數。多數系統中的默認值為`1`。 #### socket.setMulticastLoopback(flag) - flag Boolean 設置或清除`IP_MULTICAST_LOOP``socket`選項。當這個選項被設置，組播報文也將會在本地接口上接收。 #### socket.addMembership(multicastAddress[, multicastInterface]) - multicastAddress String - multicastInterface String, 可選告訴內核加入一個組播分組，通過`IP_ADD_MEMBERSHIP``socket`選項。如果`multicastInterface`沒有被指定，那么操作系統將會嘗試加入成為所有可用的接口的成員。 #### socket.dropMembership(multicastAddress[, multicastInterface]) - multicastAddress String - multicastInterface String, 可選與`addMembership`相反 - 告訴內核離開一個組播分組，通過`IP_DROP_MEMBERSHIP``socket`選項。當`socket`被關閉或進程結束時，它會被內核自動調用。所以大多數應用不需要親自調用它。如果`multicastInterface`沒有被指定，那么操作系統將會嘗試脫離所有可用的接口。 #### socket.unref() 在一個`socket`上調用`unref`將會在它是事件系統中唯一活躍的`socket`時，允許程序退出。如果`socket`已經被`unref`，再次調用將不會有任何效果。返回一個`socket`。 #### socket.ref() 與`unref`相反，在一個先前被`unref`的`socket`上調用`ref`，那么在它是唯一的剩余的`socket`（默認行為）時，將不允許程序退出。如果`socket`已經被`ref`，再次調用將不會有任何效果。返回一個`socket`。