1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: add added information for net

Browse Source 
Ref: https://github.com/nodejs/node/issues/6578
PR-URL: https://github.com/nodejs/node/pull/7038
Reviewed-By: Anna Henningsen <anna@addaleax.net>
This commit is contained in:
Italo A. Casas 2016-06-02 20:15:22 -04:00 committed by Anna Henningsen
parent 83e32266b6
commit 8bccc9e6c8
1 changed files with 175 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

175
doc/api/net.md
View File

@ -7,17 +7,26 @@ functions for creating both servers and clients (called streams). You can includ
this module with `require('net');`.
## Class: net.Server
<!-- YAML
added: v0.1.90
-->
This class is used to create a TCP or local server.
`net.Server` is an [`EventEmitter`][] with the following events:
### Event: 'close'
<!-- YAML
added: v0.5.0
-->
Emitted when the server closes. Note that if connections exist, this
event is not emitted until all connections are ended.
### Event: 'connection'
<!-- YAML
added: v0.1.90
-->
* {net.Socket} The connection object
@ -25,6 +34,9 @@ Emitted when a new connection is made. `socket` is an instance of
`net.Socket`.
### Event: 'error'
<!-- YAML
added: v0.1.90
-->
* {Error}
@ -32,10 +44,16 @@ Emitted when an error occurs. The [`'close'`][] event will be called directly
following this event. See example in discussion of `server.listen`.
### Event: 'listening'
<!-- YAML
added: v0.1.90
-->
Emitted when the server has been bound after calling `server.listen`.
### server.address()
<!-- YAML
added: v0.1.90
-->
Returns the bound address, the address family name, and port of the server
as reported by the operating system.
@ -63,6 +81,9 @@ server.listen(() => {
Don't call `server.address()` until the `'listening'` event has been emitted.
### server.close([callback])
<!-- YAML
added: v0.1.90
-->
Stops the server from accepting new connections and keeps existing
connections. This function is asynchronous, the server is finally
@ -72,6 +93,10 @@ that event, it will be called with an Error as its only argument if the server
was not open when it was closed.
### server.connections
<!-- YAML
added: v0.2.0
deprecated: v0.9.7
-->
Stability: 0 - Deprecated: Use [`server.getConnections()`][] instead.
@ -82,6 +107,9 @@ This becomes `null` when sending a socket to a child with
connections use asynchronous `server.getConnections` instead.
### server.getConnections(callback)
<!-- YAML
added: v0.9.7
-->
Asynchronously get the number of concurrent connections on the server. Works
when sockets were sent to forks.
@ -89,6 +117,9 @@ when sockets were sent to forks.
Callback should take two arguments `err` and `count`.
### server.listen(handle[, backlog][, callback])
<!-- YAML
added: v0.5.10
-->
* `handle` {Object}
* `backlog` {Number}
@ -112,6 +143,9 @@ The parameter `backlog` behaves the same as in
[`server.listen(port[, hostname][, backlog][, callback])`][`server.listen(port, host, backlog, callback)`].
### server.listen(options[, callback])
<!-- YAML
added: v0.11.14
-->
* `options` {Object} - Required. Supports the following properties:
* `port` {Number} - Optional.
@ -141,6 +175,9 @@ server.listen({
```
### server.listen(path[, backlog][, callback])
<!-- YAML
added: v0.1.90
-->
* `path` {String}
* `backlog` {Number}
@ -175,6 +212,9 @@ The parameter `backlog` behaves the same as in
[`server.listen(port[, hostname][, backlog][, callback])`][`server.listen(port, host, backlog, callback)`].
### server.listen(port[, hostname][, backlog][, callback])
<!-- YAML
added: v0.1.90
-->
Begin accepting connections on the specified `port` and `hostname`. If the
`hostname` is omitted, the server will accept connections on any IPv6 address
@ -209,11 +249,17 @@ server.on('error', (e) => {
(Note: All sockets in Node.js are set `SO_REUSEADDR`.)
### server.listening
<!-- YAML
added: v5.7.0
-->
A Boolean indicating whether or not the server is listening for
connections.
### server.maxConnections
<!-- YAML
added: v0.2.0
-->
Set this property to reject connections when the server's connection count gets
high.
@ -222,6 +268,9 @@ It is not recommended to use this option once a socket has been sent to a child
with [`child_process.fork()`][].
### server.ref()
<!-- YAML
added: v0.9.1
-->
Opposite of `unref`, calling `ref` on a previously `unref`d server will *not*
let the program exit if it's the only server left (the default behavior). If
@ -230,6 +279,9 @@ the server is `ref`d calling `ref` again will have no effect.
Returns `server`.
### server.unref()
<!-- YAML
added: v0.9.1
-->
Calling `unref` on a server will allow the program to exit if this is the only
active server in the event system. If the server is already `unref`d calling
@ -238,6 +290,9 @@ active server in the event system. If the server is already `unref`d calling
Returns `server`.
## Class: net.Socket
<!-- YAML
added: v0.3.4
-->
This object is an abstraction of a TCP or local socket. `net.Socket`
instances implement a duplex Stream interface. They can be created by the
@ -245,6 +300,9 @@ user and used as a client (with [`connect()`][]) or they can be created by Node.
and passed to the user through the `'connection'` event of a server.
### new net.Socket([options])
<!-- YAML
added: v0.3.4
-->
Construct a new socket object.
@ -267,6 +325,9 @@ About `allowHalfOpen`, refer to `createServer()` and `'end'` event.
`net.Socket` instances are [`EventEmitter`][] with the following events:
### Event: 'close'
<!-- YAML
added: v0.1.90
-->
* `had_error` {Boolean} `true` if the socket had a transmission error.
@ -274,11 +335,17 @@ Emitted once the socket is fully closed. The argument `had_error` is a boolean
which says if the socket was closed due to a transmission error.
### Event: 'connect'
<!-- YAML
added: v0.1.90
-->
Emitted when a socket connection is successfully established.
See [`connect()`][].
### Event: 'data'
<!-- YAML
added: v0.1.90
-->
* {Buffer}
@ -290,12 +357,18 @@ Note that the __data will be lost__ if there is no listener when a `Socket`
emits a `'data'` event.
### Event: 'drain'
<!-- YAML
added: v0.1.90
-->
Emitted when the write buffer becomes empty. Can be used to throttle uploads.
See also: the return values of `socket.write()`
### Event: 'end'
<!-- YAML
added: v0.1.90
-->
Emitted when the other end of the socket sends a FIN packet.
@ -306,6 +379,9 @@ its side allowing the user to write arbitrary amounts of data, with the
caveat that the user is required to `end()` their side now.
### Event: 'error'
<!-- YAML
added: v0.1.90
-->
* {Error}
@ -313,6 +389,9 @@ Emitted when an error occurs. The `'close'` event will be called directly
following this event.
### Event: 'lookup'
<!-- YAML
added: v0.11.3
-->
Emitted after resolving the hostname but before connecting.
Not applicable to UNIX sockets.
@ -323,6 +402,9 @@ Not applicable to UNIX sockets.
* `host` {String} The hostname.
### Event: 'timeout'
<!-- YAML
added: v0.1.90
-->
Emitted if the socket times out from inactivity. This is only to notify that
the socket has been idle. The user must manually close the connection.
@ -330,6 +412,9 @@ the socket has been idle. The user must manually close the connection.
See also: [`socket.setTimeout()`][]
### socket.address()
<!-- YAML
added: v0.1.90
-->
Returns the bound address, the address family name and port of the
socket as reported by the operating system. Returns an object with
@ -337,6 +422,9 @@ three properties, e.g.
`{ port: 12346, family: 'IPv4', address: '127.0.0.1' }`
### socket.bufferSize
<!-- YAML
added: v0.3.8
-->
`net.Socket` has the property that `socket.write()` always works. This is to
help users get up and running quickly. The computer cannot always keep up
@ -355,14 +443,23 @@ Users who experience large or growing `bufferSize` should attempt to
"throttle" the data flows in their program with [`pause()`][] and [`resume()`][].
### socket.bytesRead
<!-- YAML
added: v0.5.3
-->
The amount of received bytes.
### socket.bytesWritten
<!-- YAML
added: v0.5.3
-->
The amount of bytes sent.
### socket.connect(options[, connectListener])
<!-- YAML
added: v0.1.90
-->
Opens the connection for a given socket.
@ -399,22 +496,34 @@ The `connectListener` parameter will be added as a listener for the
### socket.connect(path[, connectListener])
### socket.connect(port[, host][, connectListener])
<!-- YAML
added: v0.1.90
-->
As [`socket.connect(options[, connectListener])`][`socket.connect(options, connectListener)`],
with options either as either `{port: port, host: host}` or `{path: path}`.
### socket.connecting
<!-- YAML
added: v6.1.0
-->
If `true` - [`socket.connect(options[, connectListener])`][`socket.connect(options, connectListener)`] was called and
haven't yet finished. Will be set to `false` before emitting `connect` event
and/or calling [`socket.connect(options[, connectListener])`][`socket.connect(options, connectListener)`]'s callback.
### socket.destroy()
<!-- YAML
added: v0.1.90
-->
Ensures that no more I/O activity happens on this socket. Only necessary in
case of errors (parse error or so).
### socket.end([data][, encoding])
<!-- YAML
added: v0.1.90
-->
Half-closes the socket. i.e., it sends a FIN packet. It is possible the
server will still send some data.
@ -423,12 +532,18 @@ If `data` is specified, it is equivalent to calling
`socket.write(data, encoding)` followed by `socket.end()`.
### socket.localAddress
<!-- YAML
added: v0.9.6
-->
The string representation of the local IP address the remote client is
connecting on. For example, if you are listening on `'0.0.0.0'` and the
client connects on `'192.168.1.1'`, the value would be `'192.168.1.1'`.
### socket.localPort
<!-- YAML
added: v0.9.6
-->
The numeric representation of the local port. For example,
`80` or `21`.
@ -439,6 +554,9 @@ Pauses the reading of data. That is, [`'data'`][] events will not be emitted.
Useful to throttle back an upload.
### socket.ref()
<!-- YAML
added: v0.9.1
-->
Opposite of `unref`, calling `ref` on a previously `unref`d socket will *not*
let the program exit if it's the only socket left (the default behavior). If
@ -447,16 +565,25 @@ the socket is `ref`d calling `ref` again will have no effect.
Returns `socket`.
### socket.remoteAddress
<!-- YAML
added: v0.5.10
-->
The string representation of the remote IP address. For example,
`'74.125.127.100'` or `'2001:4860:a005::68'`. Value may be `undefined` if
the socket is destroyed (for example, if the client disconnected).
### socket.remoteFamily
<!-- YAML
added: v0.11.14
-->
The string representation of the remote IP family. `'IPv4'` or `'IPv6'`.
### socket.remotePort
<!-- YAML
added: v0.5.10
-->
The numeric representation of the remote port. For example,
`80` or `21`.
@ -466,11 +593,17 @@ The numeric representation of the remote port. For example,
Resumes reading after a call to [`pause()`][].
### socket.setEncoding([encoding])
<!-- YAML
added: v0.1.90
-->
Set the encoding for the socket as a [Readable Stream][]. See
[`stream.setEncoding()`][] for more information.
### socket.setKeepAlive([enable][, initialDelay])
<!-- YAML
added: v0.1.92
-->
Enable/disable keep-alive functionality, and optionally set the initial
delay before the first keepalive probe is sent on an idle socket.
@ -484,6 +617,9 @@ initialDelay will leave the value unchanged from the default
Returns `socket`.
### socket.setNoDelay([noDelay])
<!-- YAML
added: v0.1.90
-->
Disables the Nagle algorithm. By default TCP connections use the Nagle
algorithm, they buffer data before sending it off. Setting `true` for
@ -493,6 +629,9 @@ algorithm, they buffer data before sending it off. Setting `true` for
Returns `socket`.
### socket.setTimeout(timeout[, callback])
<!-- YAML
added: v0.1.90
-->
Sets the socket to timeout after `timeout` milliseconds of inactivity on
the socket. By default `net.Socket` do not have a timeout.
@ -509,6 +648,9 @@ The optional `callback` parameter will be added as a one time listener for the
Returns `socket`.
### socket.unref()
<!-- YAML
added: v0.9.1
-->
Calling `unref` on a socket will allow the program to exit if this is the only
active socket in the event system. If the socket is already `unref`d calling
@ -517,6 +659,9 @@ active socket in the event system. If the socket is already `unref`d calling
Returns `socket`.
### socket.write(data[, encoding][, callback])
<!-- YAML
added: v0.1.90
-->
Sends data on the socket. The second parameter specifies the encoding in the
case of a string--it defaults to UTF8 encoding.
@ -529,6 +674,9 @@ The optional `callback` parameter will be executed when the data is finally
written out - this may not be immediately.
## net.connect(options[, connectListener])
<!-- YAML
added: v0.7.0
-->
A factory function, which returns a new [`net.Socket`][] and automatically
connects with the supplied `options`.
@ -565,6 +713,9 @@ const client = net.connect({path: '/tmp/echo.sock'});
```
## net.connect(path[, connectListener])
<!-- YAML
added: v0.1.90
-->
A factory function, which returns a new unix [`net.Socket`][] and automatically
connects to the supplied `path`.
@ -573,6 +724,9 @@ The `connectListener` parameter will be added as a listener for the
[`'connect'`][] event once.
## net.connect(port[, host][, connectListener])
<!-- YAML
added: v0.1.90
-->
A factory function, which returns a new [`net.Socket`][] and automatically
connects to the supplied `port` and `host`.
@ -583,6 +737,9 @@ The `connectListener` parameter will be added as a listener for the
[`'connect'`][] event once.
## net.createConnection(options[, connectListener])
<!-- YAML
added: v0.1.90
-->
A factory function, which returns a new [`net.Socket`][] and automatically
connects with the supplied `options`.
@ -619,6 +776,9 @@ const client = net.connect({path: '/tmp/echo.sock'});
```
## net.createConnection(path[, connectListener])
<!-- YAML
added: v0.1.90
-->
A factory function, which returns a new unix [`net.Socket`][] and automatically
connects to the supplied `path`.
@ -627,6 +787,9 @@ The `connectListener` parameter will be added as a listener for the
[`'connect'`][] event once.
## net.createConnection(port[, host][, connectListener])
<!-- YAML
added: v0.1.90
-->
A factory function, which returns a new [`net.Socket`][] and automatically
connects to the supplied `port` and `host`.
@ -637,6 +800,9 @@ The `connectListener` parameter will be added as a listener for the
[`'connect'`][] event once.
## net.createServer([options][, connectionListener])
<!-- YAML
added: v0.5.0
-->
Creates a new server. The `connectionListener` argument is
automatically set as a listener for the [`'connection'`][] event.
@ -704,17 +870,26 @@ nc -U /tmp/echo.sock
```
## net.isIP(input)
<!-- YAML
added: v0.3.0
-->
Tests if input is an IP address. Returns 0 for invalid strings,
returns 4 for IP version 4 addresses, and returns 6 for IP version 6 addresses.
## net.isIPv4(input)
<!-- YAML
added: v0.3.0
-->
Returns true if input is a version 4 IP address, otherwise returns false.
## net.isIPv6(input)
<!-- YAML
added: v0.3.0
-->
Returns true if input is a version 6 IP address, otherwise returns false.