IO.js Net

穩(wěn)定度: 2 - 穩(wěn)定

net模塊為你提供了異步的網(wǎng)絡調(diào)用的包裝。它同時包含了創(chuàng)建服務器和客戶端的函數(shù)。你可以通過require('net')來引入這個模塊。

net.createServer([options][, connectionListener])

創(chuàng)建一個新的TCP服務器。connectionListener參數(shù)會被自動綁定為connection事件的監(jiān)聽器。

options是一個包含下列默認值的對象：

{
  allowHalfOpen: false,
  pauseOnConnect: false
}

如果allowHalfOpen是true，那么當另一端的socket發(fā)送一個FIN報文時socket并不會自動發(fā)送FIN報文。socket變得不可讀，但是可寫。你需要明確地調(diào)用end()方法。詳見end事件。

如果pauseOnConnect是true，那么socket在每一次被連接時會暫停，并且不會讀取數(shù)據(jù)。這允許在進程間被傳遞的連接不讀取任何數(shù)據(jù)。如果要讓一個被暫停的socket開始讀取數(shù)據(jù)，調(diào)用resume()方法。

以下是一個應答服務器的例子，監(jiān)聽8124端口：

var net = require('net');
var server = net.createServer(function(c) { //'connection' listener
  console.log('client connected');
  c.on('end', function() {
    console.log('client disconnected');
  });
  c.write('hello\r\n');
  c.pipe(c);
});
server.listen(8124, function() { //'listening' listener
  console.log('server bound');
});

使用telnet測試：

telnet localhost 8124

想要監(jiān)聽socket``/tmp/echo.sock，只需改變倒數(shù)第三行：

server.listen('/tmp/echo.sock', function() { //'listening' listener

使用nc連接一個UNIX domain socket服務器：

nc -U /tmp/echo.sock

net.connect(options[, connectionListener])

net.createConnection(options[, connectionListener])

工廠函數(shù)，返回一個新的net.Socket實例，并且自動使用提供的options進行連接。

options會被同時傳遞給net.Socket構(gòu)造函數(shù)和socket.connect方法。

參數(shù)connectListener將會被立即添加為connect事件的監(jiān)聽器。

下面是一個上文應答服務器的客戶端的例子：

var net = require('net');
var client = net.connect({port: 8124},
    function() { //'connect' listener
  console.log('connected to server!');
  client.write('world!\r\n');
});
client.on('data', function(data) {
  console.log(data.toString());
  client.end();
});
client.on('end', function() {
  console.log('disconnected from server');
});

要連接socket``/tmp/echo.sock只需要改變第二行為：

var client = net.connect({path: '/tmp/echo.sock'});

net.connect(port[, host][, connectListener])

net.createConnection(port[, host][, connectListener])

工廠函數(shù)，返回一個新的net.Socket實例，并且自動使用指定的端口(port)和主機(host)進行連接。

如果host被省略，默認為localhost。

參數(shù)connectListener將會被立即添加為connect事件的監(jiān)聽器。

net.connect(path[, connectListener])

net.createConnection(path[, connectListener])

工廠函數(shù)，返回一個新的unixnet.Socket實例，并且自動使用提供的路徑(path)進行連接。

參數(shù)connectListener將會被立即添加為connect事件的監(jiān)聽器。

Class: net.Server

這個類用于創(chuàng)建一個TCP或本地服務器。

server.listen(port[, hostname][, backlog][, callback])

開始從指定端口和主機名接收連接。如果省略主機名，那么如果IPv6可用，服務器會接受從任何IPv6地址（::）來的鏈接，否則為任何IPv4地址（0.0.0.0）。如果端口為0那么將會為其設置一個隨機端口。

積壓量backlog是連接等待隊列的最大長度。實際長度由你的操作系統(tǒng)的sysctl設置決定（如linux中的tcp_max_syn_backlog和somaxconn）。這個參數(shù)的默認值是511（不是512）。

這個函數(shù)式異步的。當服務器綁定了指定端口后，listening事件將會被觸發(fā)。最后一個參數(shù)callback將會被添加為listening事件的監(jiān)聽器。

有些用戶可能遇到的情況是收到EADDRINUSE錯誤。這意味著另一個服務器已經(jīng)使用了該端口。一個解決的辦法是等待一段時間后重試。

server.on('error', function (e) {
  if (e.code == 'EADDRINUSE') {
    console.log('Address in use, retrying...');
    setTimeout(function () {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
});

（注意，io.js中所有的socket都已經(jīng)設置了SO_REUSEADDR）

server.listen(path[, callback])

• path String
• callback Function

啟動一個本地socket服務器，監(jiān)聽指定路徑（path）上的連接。

這個函數(shù)式異步的。當服務器監(jiān)聽了指定路徑后，listening事件將會被觸發(fā)。最后一個參數(shù)callback將會被添加為listening事件的監(jiān)聽器。

在UNIX中，local domain經(jīng)常被稱作UNIX domain。path是一個文件系統(tǒng)路徑名。它在被創(chuàng)建時會受相同文件名約定(same naming conventions)的限制并且進行權限檢查(permissions checks)。它在文件系統(tǒng)中可見，并且在被刪除前持續(xù)存在。

在Windows中，local doamin使用一個命名管道（named pipe）實現(xiàn)。path必須指向\\?\pipe\或\\.\pipe\.中的一個條目，但是后者可能會做一些命名管道的處理，如處理..序列。除去表現(xiàn)，命名管道空間是平坦的（flat）。管道不會持續(xù)存在，它們將在最后一個它們的引用關閉后被刪除。不要忘記，由于JavaScript的字符串轉(zhuǎn)義，你必須在指定path時使用雙反斜杠：

net.createServer().listen(
    path.join('\\\\?\\pipe', process.cwd(), 'myctl'))

server.listen(handle[, callback])

• handle Object
• callback Function

handle對象可以被設置為一個服務器或一個socket（或者任意以下劃線開頭的成員_handle），或者一個{fd: <n>}對象。

這將使得服務器使用指定句柄接受連接，但它假設文件描述符或句柄已經(jīng)被綁定至指定的端口或域名socket。

在Windows下不支持監(jiān)聽一個文件描述符。

這個函數(shù)式異步的。當服務器已被綁定后，listening事件將會被觸發(fā)。最后一個參數(shù)callback將會被添加為listening事件的監(jiān)聽器。

server.listen(options[, callback])

• options Object

• port Number 可選
• host String 可選
• backlog Number 可選
• path String 可選

• exclusive Boolean 可選

• callback Function 可選

port，host和backlog屬性，以及可選的callback函數(shù)，與server.listen(port, [host], [backlog], [callback])中表現(xiàn)一致。path可以被指定為一個UNIX socket。

如果exclusive是false（默認），那么工作集群（cluster workers）將會使用相同的底層句柄，處理的連接的職責將會被它們共享。如果exclusive是true，那么句柄是不被共享的，企圖共享將得到一個報錯的結(jié)果。下面是一個監(jiān)聽獨有端口的例子：

server.listen({
  host: 'localhost',
  port: 80,
  exclusive: true
});

server.close([callback])

使服務器停止接收新的連接并且保持已存在的連接。這個函數(shù)式異步的，當所有的連接都結(jié)束時服務器會最終關閉，并處罰一個close事件?？蛇x的，你可以傳遞一個回調(diào)函數(shù)來監(jiān)聽close事件。如果傳遞了，那么它的唯一的第一個參數(shù)將表示任何可能潛在發(fā)生的錯誤。

server.address()

返回服務器綁定的地址，協(xié)議族名和端口通過操作系統(tǒng)報告。對查找操作系統(tǒng)分配的地址哪個端口被分配非常有用。返回一個有三個屬性的對象。如{ port: 12346, family: 'IPv4', address: '127.0.0.1' }。

例子：

var server = net.createServer(function (socket) {
  socket.end("goodbye\n");
});

// grab a random port.
server.listen(function() {
  address = server.address();
  console.log("opened server on %j", address);
});

在listening事件觸發(fā)前，不要調(diào)用server.address()方法。

server.unref()

調(diào)用一個server對象的unref方法將允許如果它是事件系統(tǒng)中唯一活躍的服務器，程序?qū)顺?。如果服務器已?jīng)被調(diào)用過這個方法，那么再次調(diào)用這個方法將不會有任何效果。

返回server對象。

server.ref()

與unref相反，在一個已經(jīng)被調(diào)用unref方法的server中調(diào)用ref方法，那么如果它是唯一活躍的服務器時，程序?qū)⒉粫顺觯J）。如果服務器已經(jīng)被調(diào)用過這個方法，那么再次調(diào)用這個方法將不會有任何效果。

返回server對象。

server.maxConnections

設置了這個屬性后，服務器的連接數(shù)達到時將會開始拒絕連接。

一旦socket被使用child_process.fork()傳遞給了子進程，這個屬性就不被推薦去設置。

server.connections

這個函數(shù)已經(jīng)被棄用。請使用server.getConnections()替代。

服務器的當前連接數(shù)。

當使用child_process.fork()傳遞一個socket給子進程時，這個屬性將變成null。想要得到正確的結(jié)果請使用server.getConnections。

server.getConnections(callback)

異步地去獲取服務器的當前連接數(shù)，在socket被傳遞給子進程時仍然可用。

回調(diào)函數(shù)的兩個參數(shù)是err和count。

net.Server是一個具有以下事件的EventEmitter：

Event: 'listening'

當調(diào)用server.listen后，服務器已被綁定時觸發(fā)。

Event: 'connection'

• Socket object 連接對象

當新的連接產(chǎn)生時觸發(fā)。socket是一個net.Socket實例。

Event: 'close'

當服務器關閉時觸發(fā)。注意如果服務器中仍有連接存在，那么這個事件會直到所有的連接都關閉后才觸發(fā)。

Event: 'error'

• Error Object

當發(fā)生錯誤時觸發(fā)。close事件將會在它之后立即觸發(fā)。參閱server.listen。

Class: net.Socket

這個對象是一個TCP或本地socket的抽象。net.Socket實例實現(xiàn)了雙工流（duplex Stream）接口。它可以被使用者創(chuàng)建，并且被作為客戶端（配合connect()）使用?；蛘咭部梢员?code>io.js創(chuàng)建，并且通過服務器的connection事件傳遞給使用者。

new net.Socket([options])

創(chuàng)建一個新的socket對象。

options是一個有以下默認值的對象：

{ fd: null
  allowHalfOpen: false,
  readable: false,
  writable: false
}

fd允許你使用一個指定的已存在的socket文件描述符。設置readable 和/或 writable為true將允許從這個socket中讀 和/或 寫（注意，僅在傳遞了passed時可用）。關于allowHalfOpen，參閱createServer()和end事件。

socket.connect(options[, connectListener])

從給定的socket打開一個連接。

對于TCPsocket，options參數(shù)需是一個包含以下屬性的對象：

• port: 客戶端需要連接的端口（必選）。

• host: 客戶端需要連接的主機（默認：'localhost'）

• localAddress: 將要綁定的本地接口，為了網(wǎng)絡連接。

• localPort: 將要綁定的本地端口，為了網(wǎng)絡連接。

• family : IP協(xié)議族版本，默認為4。

• lookup : 自定義查找函數(shù)。默認為dns.lookup。

對于本地domain socket，options參數(shù)需是一個包含以下屬性的對象：

• path: 客戶端需要連接的路徑（必選）。

通常這個方法是不需要的，因為通過net.createConnection打開socket。只有在你自定義了socket時才使用它。

這個函數(shù)式異步的，當connect事件觸發(fā)時，這個socket就被建立了。如果在連接的過程有問題，那么connect事件將不會觸發(fā)，error將會帶著這個異常觸發(fā)。

connectListener參數(shù)會被自動添加為connect事件的監(jiān)聽器。

socket.connect(port[, host][, connectListener])

socket.connect(path[, connectListener])

參閱socket.connect(options[, connectListener])。

socket.bufferSize

net.Socket的屬性，用于socket.write()。它可以幫助用戶獲取更快的運行速度。計算機不能一直保持大量數(shù)據(jù)被寫入socket的狀態(tài)，網(wǎng)絡連接可以很慢。io.js在內(nèi)部會排隊等候數(shù)據(jù)被寫入socekt并確保傳輸連接上的數(shù)據(jù)完好。 (內(nèi)部實現(xiàn)為：輪詢socekt的文件描述符等待它為可寫)。

內(nèi)部緩存的可能結(jié)果是內(nèi)存使用會增長。這個屬性展示了緩存中還有多少待寫入的字符（字符的數(shù)目約等于要被寫入的字節(jié)數(shù)，但是緩沖區(qū)可能包含字符串，而字符串是惰性編碼的，所以確切的字節(jié)數(shù)是未知的）。

遇到數(shù)值很大或增長很快的bufferSize時，應當嘗試使用pause()和resume()來控制。

socket.setEncoding([encoding])

設置socket的編碼作為一個可讀流。詳情參閱stream.setEncoding()。

socket.write(data[, encoding][, callback])

在套接字上發(fā)送數(shù)據(jù)。第二個參數(shù)指定了字符串的編碼，默認為UTF8。

如果所有數(shù)據(jù)成功被刷新至了內(nèi)核緩沖區(qū)，則返回true。如果所有或部分數(shù)據(jù)仍然在用戶內(nèi)存中排隊，則返回false。drain事件將會被觸發(fā)當buffer再次為空時。

當數(shù)據(jù)最終被寫入時，callback回調(diào)函數(shù)將會被執(zhí)行，但可能不會馬上執(zhí)行。

socket.end([data][, encoding])

半關閉一個socket。比如，它發(fā)送一個FIN報文?？赡芊掌魅匀辉诎l(fā)送一些數(shù)據(jù)。

如果data參數(shù)被指定，那么等同于先調(diào)用socket.write(data, encoding)，再調(diào)用socket.end()。

socket.destroy()

確保這個socket上沒有I/O活動發(fā)生。只在發(fā)生錯誤情況才需要（如處理錯誤）。

socket.pause()

暫停數(shù)據(jù)讀取。data事件將不會再觸發(fā)。對于控制上傳非常有用。

socket.resume()

用于在調(diào)用pause()后，恢復數(shù)據(jù)讀取。

socket.setTimeout(timeout[, callback])

如果socket在timeout毫秒中沒有活動后，設置其為超時。默認情況下，net.Socket沒有超時。

當超時發(fā)生，socket會收到一個timeout事件，但是連接將不會被斷開。用戶必須手動地調(diào)用end()或destroy()方法。

如果timeout是0，那么現(xiàn)有的超時將會被禁用。

可選的callback參數(shù)就會被自動添加為timeout事件的監(jiān)聽器。

返回一個socket。

socket.setNoDelay([noDelay])

警用納格算法（Nagle algorithm）。默認情況下TCP連接使用納格算法，它們的數(shù)據(jù)在被發(fā)送前會被緩存。設置noDelay為true將會在每次socket.write()時立刻發(fā)送數(shù)據(jù)。noDelay默認為true。

返回一個socket。

socket.setKeepAlive([enable][, initialDelay])

啟用/警用長連接功能，并且在第一個在閑置socket的長連接probe被發(fā)送前，可選得設置初始延時。enable默認為false。

設定initialDelay(毫秒)，來設定在收到的最后一個數(shù)據(jù)包和第一個長連接probe之間的延時。將initialDelay設成0會讓值保持不變(默認值或之前所設的值)。默認為0。

返回一個socket。

socket.address()

返回綁定的地址，協(xié)議族名和端口通過操作系統(tǒng)報告。對查找操作系統(tǒng)分配的地址哪個端口被分配非常有用。返回一個有三個屬性的對象。如{ port: 12346, family: 'IPv4', address: '127.0.0.1' }。

socket.unref()

調(diào)用一個socket對象的unref方法將允許如果它是事件系統(tǒng)中唯一活躍的socket，程序?qū)顺?。如?code>socket已經(jīng)被調(diào)用過這個方法，那么再次調(diào)用這個方法將不會有任何效果。

返回socket對象。

socket.ref()

與unref相反，在一個已經(jīng)被調(diào)用unref方法的socket中調(diào)用ref方法，那么如果它是唯一活躍的socket時，程序?qū)⒉粫顺觯J）。如果socket已經(jīng)被調(diào)用過這個方法，那么再次調(diào)用這個方法將不會有任何效果。

返回socket對象。

socket.remoteAddress

遠程IP地址字符串。例如，'74.125.127.100'或'2001:4860:a005::68'。

socket.remoteFamily

遠程IP協(xié)議族字符串。例如，'IPv4'或'IPv6'。

socket.remotePort

遠程端口數(shù)值。例如，80或21。

socket.localAddress

遠程客戶端正連接的本地IP地址字符串。例如，如果你正在監(jiān)聽'0.0.0.0'并且客戶端連接在'192.168.1.1'，其值將為'192.168.1.1'。

socket.localPort

本地端口數(shù)值。例如，80或21。

socket.bytesRead

接受的字節(jié)數(shù)。

socket.bytesWritten

發(fā)送的字節(jié)數(shù)。

net.Socket net.Socket實例是一個包含以下事件的EventEmitter：

Event: 'lookup'

在解析主機名后，連接主機前觸發(fā)。對UNIX socket不適用。

• err {Error | Null} 錯誤對象，參閱 dns.lookup()
• address {String} IP地址
• family {String | Null} 地址類型。參閱'dns.lookup()`

Event: 'connect'

在socket連接成功建立后觸發(fā)。參閱connect()。

Event: 'data'

• Buffer object

在接受到數(shù)據(jù)后觸發(fā)。參數(shù)將會是一個Buffer或一個字符串。數(shù)據(jù)的編碼由socket.setEncoding()設置（更多詳細信息請查看可讀流章節(jié)）。

注意，當socket觸發(fā)data事件時，如果沒有監(jiān)聽器存在。那么數(shù)據(jù)將會丟失。

Event: 'end'

當另一端的socket發(fā)送一個FIN報文時觸發(fā)。

默認情況（allowHalfOpen == false）下，一旦一個socket的文件描述符被從它的等待寫隊列（pending write queue）中寫出，socket會銷毀它。但是，當設定allowHalfOpen == true后，socket不會在它這邊自動調(diào)用end()，允許用戶寫入任意數(shù)量的數(shù)據(jù)，需要注意的是用戶需要在自己這邊調(diào)用end()。

Event: 'timeout'

當socket因不活動而超時時觸發(fā)。這只是來表示socket被限制。用戶必須手動關閉連接。

參閱socket.setTimeout()。

Event: 'drain'

當寫緩沖為空時觸發(fā)?？梢员挥脕砜刂粕蟼髁髁俊?/p>

參閱socket.write()的返回值。

Event: 'error'

• Error object

當發(fā)生錯誤時觸發(fā)。close事件會緊跟著這個事件觸發(fā)。

Event: 'close'

• had_error 如果socket有一個傳輸錯誤時為true

當socket完全關閉時觸發(fā)。參數(shù)had_error是一個表示socket是否是因為傳輸錯誤而關閉的布爾值。

net.isIP(input)

測試input是否是一個IP地址。如果是不合法字符串時，會返回0。如果是IPv4地址則返回4，是IPv6地址則返回6。

net.isIPv4(input)

如果input是一個IPv4地址則返回true，否則返回false。

net.isIPv6(input)

如果input是一個IPv6地址則返回true，否則返回false。