lukechilds
/
node
mirror of https://github.com/lukechilds/node.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

doc refactor: net

v0.8.7-release
isaacs 13 years ago
parent
e88a1ba74a
commit
e8ad5b9c1c
1 changed files with 51 additions and 71 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 122
      doc/api/net.markdown

122
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(arguments...)
### net.createConnection(arguments...)
## net.connect(arguments...)
## net.createConnection(arguments...)
Construct a new socket object and opens a socket to the given location. When
the socket is established the ['connect'](#event_connect_) event will be
@ -92,14 +92,12 @@ changed to
var client = net.connect('/tmp/echo.sock', function() { //'connect' listener
---
### 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
@ -127,7 +125,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`.
@ -136,14 +134,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()
### server.close()
Stops the server from accepting new connections. This function is
asynchronous, the server is finally closed when the server emits a `'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.
@ -163,54 +161,48 @@ 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'
`function () {}`
### Event: 'listening'
Emitted when the server has been bound after calling `server.listen`.
#### Event: 'connection'
### Event: 'connection'
`function (socket) {}`
* {Socket object} The connection object
Emitted when a new connection is made. `socket` is an instance of
`net.Socket`.
#### Event: 'close'
`function () {}`
### Event: 'close'
Emitted when the server closes.
#### Event: 'error'
### Event: 'error'
`function (exception) {}`
* {Error Object}
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.
@ -225,8 +217,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,
@ -246,7 +238,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
@ -265,18 +257,18 @@ 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.setSecure()
### socket.setSecure()
This function has been removed in v0.3. It used to upgrade the connection to
SSL/TLS. See the [TLS section](tls.html#tLS_) for the new API.
#### 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.
@ -288,12 +280,12 @@ 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.write(data, [encoding], [callback])
### socket.write(data, [encoding], [callback])
Write data with the optional encoding. The callback will be made when the
data is flushed to the kernel.
#### 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.
@ -301,21 +293,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.
@ -329,14 +321,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.
@ -347,43 +339,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'
`function () { }`
### Event: 'connect'
Emitted when a socket connection is successfully established.
See `connect()`.
#### Event: 'data'
### Event: 'data'
`function (data) { }`
* {Buffer object}
Emitted when data is received. The argument `data` will be a `Buffer` or
`String`. Encoding of data is set by `socket.setEncoding()`.
@ -393,9 +383,7 @@ information.)
Note that the __data will be lost__ if there is no listener when a `Socket`
emits a `'data'` event.
#### Event: 'end'
`function () { }`
### Event: 'end'
Emitted when the other end of the socket sends a FIN packet.
@ -406,9 +394,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'
`function () { }`
### Event: 'timeout'
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.
@ -416,44 +402,38 @@ the socket has been idle. The user must manually close the connection.
See also: `socket.setTimeout()`
#### Event: 'drain'
`function () { }`
### Event: 'drain'
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) { }`
* {Error object}
Emitted when an error occurs. The `'close'` event will be called directly
following this event.
#### Event: 'close'
### Event: 'close'
`function (had_error) { }`
* `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.
---
### net.isIP
#### net.isIP(input)
## 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.

Write Preview
Loading…
Cancel
Save