net模块

net（网络）

net 模块用于创建基于流的 TCP 或 IPC 的服务器（net.createServer()）与客户端（net.createConnection()）。

net.Server 类

此类用于创建 TCP 或 IPC 服务器。

new net.Server([options][, connectionListener])

options <Object> 参阅 net.createServer([options][, connectionListener])。
connectionListener <Function> 自动设置为 'connection' 事件的监听器。
返回: <net.Server>

net.Server 是一个 EventEmitter，实现了以下事件: 

'close' 事件

当 server 关闭的时候触发。 如果有连接存在，直到所有的连接结束才会触发这个事件。

'connection' 事件

• <net.Socket> 连接对象。

当一个新的连接建立的时候触发。 socket 是一个 net.Socket 实例。

'error' 事件

<Error>
当错误出现的时候触发。 不同于 net.Socket，'close' 事件不会在这个事件触发后继续触发，除非 server.close() 是手动调用。 参阅 server.listen() 中的例子。

'listening' 事件

当调用 server.listen() 绑定服务器之后触发。

server.address()

如果在 IP socket 上监听，则返回操作系统报告的绑定的 address、地址 family 名称、以及服务器 port（用于查找在获取操作系统分配的地址时分配的端口）：{ port: 12346, family: 'IPv4', address: '127.0.0.1' }。

不要在 'listening' 事件触发之前调用 server.address()。

server.close([callback])

callback <Function> 当 server 被关闭时调用。
返回: <net.Server>
阻止 server 接受新的连接并保持现有的连接。 该函数是异步的，server 将在所有连接结束后关闭并触发 'close' 事件。 可选的 callback 将在 'close' 事件发生时被调用。 与 'close' 事件不同的是，如果 server 在关闭时未打开，回调函数被调用时会传入一个 Error 对象作为唯一参数。

server.connections

callback <Function>
返回: <net.Server>
异步获取服务器的当前并发连接数。当 socket 被传递给子进程时工作。

回调函数的两个参数是 err 和 count。

server.getConnections(callback)

启动一个服务器来监听连接。 net.Server 可以是 TCP 或 IPC 服务器，具体取决于它监听的内容。

server.listen()

可能的参数：

• server.listen(handle[, backlog][, callback])
• server.listen(options[, callback])
• server.listen(path[, backlog][, callback]) 用于 IPC 服务器。
• server.listen([port[, host[, backlog]]][, callback]) 用于 TCP 服务器。

这个函数是异步的。当服务器开始监听时，会触发 'listening' 事件。 最后一个参数 callback 将被添加为 'listening' 事件的监听器。

server.listen(handle[, backlog][, callback])

<boolean> 表明 server 是否正在监听连接。

server.maxConnections

<integer>
设置该属性使得当 server 连接数过多时拒绝连接。

一旦将一个 socket 发送给 child_process.fork() 生成的子进程，就不推荐使用该选项。

server.ref()

返回: <net.Server>
与 unref() 相反，在一个已经调用 unref 的 server 中调用 ref()，如果 server 是仅存的 server，则程序不会退出（默认）。对一个已经调用 ref 的 server 再次调用 ref() 将不会再有效果。

server.unref()

• 返回: <net.Server>

如果这个 server 在事件系统中是唯一有效的，那么对 server 调用 unref() 将允许程序退出。 如果这个 server 已经调用过 unref 那么再次调用 unref() 将不会再有效果。

net.Socket 类

此类是 TCP 套接字或流式 IPC 端点的抽象（在 Windows 上使用命名管道，否则使用 Unix 域套接字）。 它也是一个 EventEmitter。

net.Socket 可以由用户创建并且直接地与服务器进行交互。 例如，它由 net.createConnection() 返回，因此用户可以使用它与服务器进行通信。

它也可以由 Node.js 创建，并在收到连接时传给用户。 例如，将它传给 net.Server 上触发的 'connection' 事件的监听器，因此用户可以使用它与客户端进行交互。

new net.Socket([options])

options <Object> 可用选项有

fd <number> 如果指定了该参数，则使用一个给定的文件描述符包装一个已存在的 socket，否则将创建一个新的 socket。
allowHalfOpen <boolean> 指示是否允许半打开的 TCP 连接。详情查看 net.createServer() 和 'end' 事件。默认值: false。
readable <boolean> 当传递了 fd 时允许读取 socket，否则忽略。默认值: false。
writable <boolean> 当传递了 fd 时允许写入 socket，否则忽略。默认值: false。
返回: <net.Socket>
创建一个 socket 对象。 新创建的 socket 可以是 TCP socket 也可以是 IPC 端点流，取决于它连接 connect() 到什么。

'close' 事件

had_error <boolean> 如果 socket 有传输错误就为 true。
一旦 socket 完全关闭就发出该事件。参数 had_error 是 boolean 类型，表明 socket 被关闭是否取决于传输错误。

'connect' 事件

当一个 socket 连接成功建立的时候触发该事件。 查看 net.createConnection()。

'data' 事件

当接收到数据的时触发该事件。data 参数是一个 Buffer 或 String。数据编码由 socket.setEncoding() 设置。

当 Socket 触发 'data' 事件的时候，如果没有监听器则数据将会丢失。

'drain' 事件

当写入缓冲区变为空时触发。可以用来做上传节流。

也可以查看：socket.write() 的返回值。

'end' 事件

当 socket 的另一端发送一个 FIN 包的时候触发，从而结束 socket 的可读端。

默认情况下（allowHalfOpen 为 false），socket 将发送一个 FIN 数据包，并且一旦写出它的等待写入队列就销毁它的文件描述符。 当然，如果 allowHalfOpen 为 true，socket 就不会自动结束 end() 它的写入端，允许用户写入任意数量的数据。 用户必须调用 end() 显式地结束这个连接（例如发送一个 FIN 数据包）。

'error' 事件

• <Error>

当错误发生时触发。'close' 事件也会紧接着该事件被触发。

'lookup' 事件

在找到主机之后创建连接之前触发。不可用于 Unix socket。

err <Error> | <null> 错误对象。查看 dns.lookup()。
address <string> IP 地址。
family <string> | <null> 地址类型。查看 dns.lookup()。
host <string> 主机。

'ready' 事件

套接字准备好使用时触发。

'connect' 后立即触发。

'timeout' 事件

当 socket 超时的时候触发。该事件只是用来通知 socket 已经闲置。用户必须手动关闭。

也可以查看：socket.setTimeout()。

socket.address()

• 返回: <Object>

返回操作系统报告的 socket 的 address、地址的 family 名称、以及 port： { port: 12346, family: 'IPv4', address: '127.0.0.1' }。

socket.bufferSize

此属性显示为写入而缓冲的字符数。 缓冲器中可能包含字符串，其编码后的长度是未知的。 因此，此数字仅是缓冲器中字节数的近似值。

net.Socket 具有该属性时，则 socket.write() 始终可用。 这是为了帮助用户快速启动并运行。 计算机不能总是跟上写入套接字的数据量。 网络连接也可能太慢。 Node.js 将会在内部将写入套接字的数据进行排队，并在可能的情况下将其发送出去。

这种内部缓冲的结果是内存可能会增加。 对于遇到 bufferSize 太大或不断增加的用户，应尝试使用 socket.pause() 和 socket.resume() 来对其程序中的数据流进行节流。

socket.bytesRead

• <integer>

接收的字节数量。

socket.bytesWritten

• <integer>

发送的字节数量。

socket.connect()

在给定的套接字上启动一个连接。

可能的签名：

• socket.connect(options[, connectListener])
• socket.connect(path[, connectListener]) 用于 IPC 连接。
• socket.connect(port[, host][, connectListener]) 用于 TCP 连接。
• 返回: <net.Socket> socket 自身。

该方法是异步的。当连接建立了的时候，'connect' 事件将会被触发。如果连接过程中有问题，'error' 事件将会代替 'connect' 事件被触发，并将错误信息传递给 'error' 监听器。 最后一个参数 connectListener，如果指定了，将会被添加为 'connect' 事件的监听器。

socket.connect(options[, connectListener])

socket.connect(path[, connectListener])

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

socket.connecting

socket.destroy([exception])

• exception <Object>
• 返回: <net.Socket>

确保在该 socket 上不再有 I/O 活动。仅在出现错误的时候才需要（如解析错误等）。

如果制定了 exception，则将会触发一个 'error' 事件，任何监听器都将接收到 exception 作为一个参数。

socket.destroyed

<boolean> 指示连接是否已经被销毁。一旦连接被销毁就不能再使用它传输任何数据。

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

• data <string> | <Buffer> | <Uint8Array>
• encoding <string> 仅当 data 是字符串时有效。默认值: 'utf8'。
• callback <Function> 当 socket 完成时的回调函数。
• 返回: <net.Socket> socket 本身。

半关闭 socket。 例如发送一个 FIN 包。 服务端仍可以发送数据。

如果指定了 data，则相当于调用 socket.write(data, encoding) 之后再调用 socket.end()。

socket.localAddress

• <string>

远程客户端连接的本地 IP 地址字符串。例如，一个服务端正在连接到 '0.0.0.0'，客户端连接到的是 '192.168.1.1'，则 socket.localAddress 的值是 '192.168.1.1'。

socket.localPort

• <integer>

用数字表示的本地端口。例如 80 或 21。

socket.pause()

• 返回: <net.Socket> Socket 本身。

暂停读写数据。也就是说，'data' 事件将不会再被触发。可以用于上传节流。

socket.pending

• <boolean>

如果 socket 尚未连接，则为 true，因为尚未调用 .connect() 或者因为它仍处于连接过程中（参阅 socket.connecting）。

socket.ref()

• 返回: <net.Socket> Socket 本身。

与 unref() 相反，在一个已经调用 unref 的 socket 中调用 ref()，如果 socket 是仅存的 socket，则程序不会退出（默认）。 对一个已经调用 ref 的 socket 再次调用 ref 将不会再有效果。

socket.remoteAddress

• <string>

用字符串表示的远程 IP 地址。例如 '74.125.127.100' 或 '2001:4860:a005::68'。如果 socket 被销毁了（如客户端已经失去连接）则其值为 undefined。

socket.remoteFamily

• <string>

用字符串表示的远程 IP 协议族。'IPv4' 或 'IPv6'。

socket.remotePort

新增于: v0.5.10

• <integer>

用数字表示的远程端口。例如 80 或 21。

socket.resume()

• 返回: <net.Socket> Socket 本身。

在调用 socket.pause() 之后恢复读取数据。

socket.setEncoding([encoding])

• encoding <string>
• 返回: <net.Socket> Socket 本身。

设置作为可读流的编码。在 readable.setEncoding() 查看更多详情。

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

• enable <boolean> 默认值: false。
• initialDelay <number> 默认值: 0。
• 返回: <net.Socket> Socket 本身。

启用/禁用长连接功能， 并且在第一个长连接探针被发送到一个空闲的 socket 之前可选则配置初始延迟。

initialDelay（毫秒）用来设置接收到最后一个数据包和发送第一个长连接探针之间的延迟。将 initialDelay 设置为 0，则会保持默认值（或之前设置的值）不变。

socket.setNoDelay([noDelay])

• noDelay <boolean> 默认值: true。
• 返回: <net.Socket> Socket 本身。

禁止 Nagle 算法。默认情况下 TCP 连接使用 Nagle 算法，在发送之前缓冲数据。将 noDelay 设置为 true 将会在每次 socket.write() 被调用的时候立即发送数据。

socket.setTimeout(timeout[, callback])

• timeout <number>
• callback <Function>
• 返回: <net.Socket> Socket 本身。

当 socket 在 timeout 毫秒不活动之后将其设置为超时状态。默认 net.Socket 没有超时。

当一个闲置的超时被触发，socket 将会收到一个 'timeout' 事件，但连接不会被断开。用户必须手动调用 socket.end() 或 socket.destroy() 来断开连接。

socket.unref()

• 返回: <net.Socket> Socket 本身。

如果活跃的 socket 是事件系统中仅存的 socket，则调用 unref() 将会允许程序退出。对一个已经调用了 unref 的 socket 再调用 unref() 无效。

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

• data <string> | <Buffer> | <Uint8Array>
• encoding <string> 仅在数据为 string 时使用。默认值: utf8。
• callback <Function>
• 返回: <boolean>

在 socket 上发送数据。第二个参数制定了字符串的编码 - 默认是 UTF8 编码。

如果全部数据都成功刷新到内核的缓冲则返回 true。如果全部或部分数据在用户内中排队，则返回 false。当缓冲再次空闲的时候将触发 'drain' 事件。

当数据最终都被写出之后，可选的 callback 参数将会被执行（可能不会立即执行）。

详见 Writable 流的 write() 方法。

net.connect()

net.connect(options[, connectListener])

net.connect(path[, connectListener])

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

net.createConnection()

net.createConnection(options[, connectListener])

• options <Object> 必须。调用 new net.Socket([options]) 和 socket.connect(options[, connectListener]) 方法都会传入。
• connectListener <Function> net.createConnection() 方法的通用参数。如果制定了，将被添加为返回 socket 上的 'connect' 事件上的监听器。
• 返回: <net.Socket> 新创建的 socket，用于开始连接。

可选的选项，查看 new net.Socket([options]) 和 socket.connect(options[, connectListener])。

附加的选项：

• timeout <number> 如果设置，将会用来在 socket 创建之后连接开始之前调用 socket.setTimeout(timeout)。

下面是在 net.createServer() 章节描述的 server 的客户端示例：

net.createConnection(path[, connectListener])

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

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

• options <Object>

  • allowHalfOpen <boolean> 表明是否允许半开的 TCP 连接。默认值: false。
  • pauseOnConnect <boolean> 表明是否应在传入连接上暂停套接字。默认值: false。
• connectionListener <Function> 自动设置为 'connection' 事件的监听器。
• 返回: <net.Server>

创建一个新的 TCP 或 IPC 服务器。

如果 allowHalfOpen 被设置为 true，则当套接字的另一端发送 FIN 数据包时，服务器将仅在 socket.end() 被显式调用发回 FIN 数据包，直到此时连接为半封闭状态（不可读但仍然可写）。 有关详细信息，参阅 'end' 事件和 RFC 1122（第 4.2.2.13 节）。

如果 pauseOnConnect 被设置为 true，则与每个传入连接关联的套接字会被暂停，并且不会从其句柄读取任何数据。 这允许在进程之间传递连接，而原始进程不会读取任何数据。 要从暂停的套接字开始读取数据，则调用 socket.resume()。

服务器可以是一个 TCP 服务器或 IPC 服务器，这取决于 listen() 监听什么。

net.isIP(input)

• input <string>
• 返回: <integer>

测试输入是否是 IP 地址。无效的字符串则返回 0，IPv4 地址则返回 4，IPv6 的地址则返回 6。

net.isIPv4(input)

• input <string>
• 返回: <boolean>

如果输入是 IPv4 地址则返回 true，否则返回 false。

net.isIPv6(input)

• input <string>
• 返回: <boolean>

如果输入是 IPv6 地址则返回 true，否则返回 false。