Skip to content

Commit

Permalink
doc: add added information for net
Browse files Browse the repository at this point in the history
Ref: #6578
PR-URL: #7038
Reviewed-By: Anna Henningsen <[email protected]>
italoacasas authored and evanlucas committed Jun 15, 2016
1 parent d4a2c82 commit 026bf17
Showing 1 changed file with 175 additions and 0 deletions.
175 changes: 175 additions & 0 deletions doc/api/net.md
Original file line number Diff line number Diff line change
@@ -7,35 +7,53 @@ 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

Emitted when a new connection is made. `socket` is an instance of
`net.Socket`.

### Event: 'error'
<!-- YAML
added: v0.1.90
-->

* {Error}

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,13 +107,19 @@ 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.

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,13 +290,19 @@ 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
user and used as a client (with [`connect()`][]) or they can be created by Node.js
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,18 +325,27 @@ 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.

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,13 +379,19 @@ 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}

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,20 +402,29 @@ 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.

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
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.

0 comments on commit 026bf17

Please sign in to comment.