github/node-v0.x-archive
1
1
Fork 0
mirror of https://github.com/nodejs/node-v0.x-archive.git synced 2026-04-28 03:01:10 -04:00
Code Issues Packages Projects Releases Wiki Activity

doc refactor: net

Browse Source
This commit is contained in:
isaacs
2012-02-27 11:09:34 -08:00
parent 0cf7156f08
commit 2fd5cb3d2e
1 changed files with 49 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

105
doc/api/net.markdown
View File

@@ -1,10 +1,10 @@
## net
# net
The `net` module provides you with an asynchronous network wrapper. It contains
methods for creating both servers and clients (called streams). You can include
this module with `require('net');`
### net.createServer([options], [connectionListener])
## net.createServer([options], [connectionListener])
Creates a new TCP server. The `connectionListener` argument is
automatically set as a listener for the ['connection'](#event_connection_)
@@ -49,8 +49,8 @@ Use `nc` to connect to a UNIX domain socket server:
nc -U /tmp/echo.sock
### net.connect(options, [cnnectionListener])
### net.createConnection(options, [cnnectionListener])
## net.connect(options, [cnnectionListener])
## net.createConnection(options, [cnnectionListener])
Constructs a new socket object and opens the socket to the given location.
When the socket is established, the ['connect'](#event_connect_) event will be
@@ -97,29 +97,27 @@ changed to
var client = net.connect({path: '/tmp/echo.sock'},
### net.connect(port, [host], [connectListener])
### net.createConnection(port, [host], [connectListener])
## net.connect(port, [host], [connectListener])
## net.createConnection(port, [host], [connectListener])
Creates a TCP connection to `port` on `host`. If `host` is omitted,
`'localhost'` will be assumed.
The `connectListener` parameter will be added as an listener for the
['connect'](#event_connect_) event.
### net.connect(path, [connectListener])
### net.createConnection(path, [connectListener])
## net.connect(path, [connectListener])
## net.createConnection(path, [connectListener])
Creates unix socket connection to `path`.
The `connectListener` parameter will be added as an listener for the
['connect'](#event_connect_) event.
---
### net.Server
## Class: net.Server
This class is used to create a TCP or UNIX server.
A server is a `net.Socket` that can listen for new incoming connections.
#### server.listen(port, [host], [listeningListener])
### server.listen(port, [host], [listeningListener])
Begin accepting connections on the specified `port` and `host`. If the
`host` is omitted, the server will accept connections directed to any
@@ -147,7 +145,7 @@ would be to wait a second and then try again. This can be done with
(Note: All sockets in Node set `SO_REUSEADDR` already)
#### server.listen(path, [listeningListener])
### server.listen(path, [listeningListener])
Start a UNIX socket server listening for connections on the given `path`.
@@ -156,14 +154,14 @@ This function is asynchronous. When the server has been bound,
the last parameter `listeningListener` will be added as an listener for the
['listening'](#event_listening_) event.
#### server.close([cb])
### server.close([cb])
Stops the server from accepting new connections. This function is
asynchronous, the server is finally closed when the server emits a `'close'`
event. Optionally, you can pass a callback to listen for the `'close'` event.
#### server.address()
### server.address()
Returns the bound address and port of the server as reported by the operating system.
Useful to find which port was assigned when giving getting an OS-assigned address.
@@ -183,54 +181,52 @@ Example:
Don't call `server.address()` until the `'listening'` event has been emitted.
#### server.maxConnections
### server.maxConnections
Set this property to reject connections when the server's connection count gets
high.
#### server.connections
### server.connections
The number of concurrent connections on the server.
`net.Server` is an `EventEmitter` with the following events:
#### Event: 'listening'
### Event: 'listening'
`function () {}`
Emitted when the server has been bound after calling `server.listen`.
#### Event: 'connection'
### Event: 'connection'
`function (socket) {}`
Emitted when a new connection is made. `socket` is an instance of
`net.Socket`.
#### Event: 'close'
### Event: 'close'
`function () {}`
Emitted when the server closes.
#### Event: 'error'
### Event: 'error'
`function (exception) {}`
Emitted when an error occurs. The `'close'` event will be called directly
following this event. See example in discussion of `server.listen`.
---
### net.Socket
## Class: net.Socket
This object is an abstraction of a TCP or UNIX 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
and passed to the user through the `'connection'` event of a server.
#### new net.Socket([options])
### new net.Socket([options])
Construct a new socket object.
@@ -245,8 +241,8 @@ Construct a new socket object.
specified underlying protocol. It can be `'tcp4'`, `'tcp6'`, or `'unix'`.
About `allowHalfOpen`, refer to `createServer()` and `'end'` event.
#### socket.connect(port, [host], [connectListener])
#### socket.connect(path, [connectListener])
### socket.connect(port, [host], [connectListener])
### socket.connect(path, [connectListener])
Opens the connection for a given socket. If `port` and `host` are given,
then the socket will be opened as a TCP socket, if `host` is omitted,
@@ -266,7 +262,7 @@ The `connectListener` parameter will be added as an listener for the
['connect'](#event_connect_) event.
#### socket.bufferSize
### socket.bufferSize
`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
@@ -285,12 +281,12 @@ Users who experience large or growing `bufferSize` should attempt to
"throttle" the data flows in their program with `pause()` and `resume()`.
#### socket.setEncoding([encoding])
### socket.setEncoding([encoding])
Sets the encoding (either `'ascii'`, `'utf8'`, or `'base64'`) for data that is
received. Defaults to `null`.
#### socket.write(data, [encoding], [callback])
### socket.write(data, [encoding], [callback])
Sends data on the socket. The second parameter specifies the encoding in the
case of a string--it defaults to UTF8 encoding.
@@ -302,7 +298,7 @@ buffer. Returns `false` if all or part of the data was queued in user memory.
The optional `callback` parameter will be executed when the data is finally
written out - this may not be immediately.
#### socket.end([data], [encoding])
### socket.end([data], [encoding])
Half-closes the socket. i.e., it sends a FIN packet. It is possible the
server will still send some data.
@@ -310,21 +306,21 @@ server will still send some data.
If `data` is specified, it is equivalent to calling
`socket.write(data, encoding)` followed by `socket.end()`.
#### socket.destroy()
### socket.destroy()
Ensures that no more I/O activity happens on this socket. Only necessary in
case of errors (parse error or so).
#### socket.pause()
### socket.pause()
Pauses the reading of data. That is, `'data'` events will not be emitted.
Useful to throttle back an upload.
#### socket.resume()
### socket.resume()
Resumes reading after a call to `pause()`.
#### socket.setTimeout(timeout, [callback])
### socket.setTimeout(timeout, [callback])
Sets the socket to timeout after `timeout` milliseconds of inactivity on
the socket. By default `net.Socket` do not have a timeout.
@@ -338,14 +334,14 @@ If `timeout` is 0, then the existing idle timeout is disabled.
The optional `callback` parameter will be added as a one time listener for the
`'timeout'` event.
#### socket.setNoDelay([noDelay])
### socket.setNoDelay([noDelay])
Disables the Nagle algorithm. By default TCP connections use the Nagle
algorithm, they buffer data before sending it off. Setting `true` for
`noDelay` will immediately fire off data each time `socket.write()` is called.
`noDelay` defaults to `true`.
#### socket.setKeepAlive([enable], [initialDelay])
### socket.setKeepAlive([enable], [initialDelay])
Enable/disable keep-alive functionality, and optionally set the initial
delay before the first keepalive probe is sent on an idle socket.
@@ -356,41 +352,41 @@ data packet received and the first keepalive probe. Setting 0 for
initialDelay will leave the value unchanged from the default
(or previous) setting. Defaults to `0`.
#### socket.address()
### socket.address()
Returns the bound address and port of the socket as reported by the operating
system. Returns an object with two properties, e.g.
`{"address":"192.168.57.1", "port":62053}`
#### socket.remoteAddress
### socket.remoteAddress
The string representation of the remote IP address. For example,
`'74.125.127.100'` or `'2001:4860:a005::68'`.
#### socket.remotePort
### socket.remotePort
The numeric representation of the remote port. For example,
`80` or `21`.
#### socket.bytesRead
### socket.bytesRead
The amount of received bytes.
#### socket.bytesWritten
### socket.bytesWritten
The amount of bytes sent.
`net.Socket` instances are EventEmitters with the following events:
#### Event: 'connect'
### Event: 'connect'
`function () { }`
Emitted when a socket connection is successfully established.
See `connect()`.
#### Event: 'data'
### Event: 'data'
`function (data) { }`
@@ -402,7 +398,7 @@ information.)
Note that the __data will be lost__ if there is no listener when a `Socket`
emits a `'data'` event.
#### Event: 'end'
### Event: 'end'
`function () { }`
@@ -415,7 +411,7 @@ 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: 'timeout'
### Event: 'timeout'
`function () { }`
@@ -425,7 +421,7 @@ the socket has been idle. The user must manually close the connection.
See also: `socket.setTimeout()`
#### Event: 'drain'
### Event: 'drain'
`function () { }`
@@ -433,36 +429,33 @@ Emitted when the write buffer becomes empty. Can be used to throttle uploads.
See also: the return values of `socket.write()`
#### Event: 'error'
### Event: 'error'
`function (exception) { }`
Emitted when an error occurs. The `'close'` event will be called directly
following this event.
#### Event: 'close'
### Event: 'close'
`function (had_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.
---
### net.isIP
#### net.isIP(input)
## net.isIP
## net.isIP(input)
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)
## net.isIPv4(input)
Returns true if input is a version 4 IP address, otherwise returns false.
#### net.isIPv6(input)
## net.isIPv6(input)
Returns true if input is a version 6 IP address, otherwise returns false.