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.9.1-release
isaacs 13 years ago
parent
0cf7156f08
commit
2fd5cb3d2e
1 changed files with 49 additions and 56 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 105
      doc/api/net.markdown

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 The `net` module provides you with an asynchronous network wrapper. It contains
methods for creating both servers and clients (called streams). You can include methods for creating both servers and clients (called streams). You can include
this module with `require('net');` this module with `require('net');`
### net.createServer([options], [connectionListener]) ## net.createServer([options], [connectionListener])
Creates a new TCP server. The `connectionListener` argument is Creates a new TCP server. The `connectionListener` argument is
automatically set as a listener for the ['connection'](#event_connection_) 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 nc -U /tmp/echo.sock
### net.connect(options, [cnnectionListener]) ## net.connect(options, [cnnectionListener])
### net.createConnection(options, [cnnectionListener]) ## net.createConnection(options, [cnnectionListener])
Constructs a new socket object and opens the socket to the given location. 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 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'}, var client = net.connect({path: '/tmp/echo.sock'},
### net.connect(port, [host], [connectListener]) ## net.connect(port, [host], [connectListener])
### net.createConnection(port, [host], [connectListener]) ## net.createConnection(port, [host], [connectListener])
Creates a TCP connection to `port` on `host`. If `host` is omitted, Creates a TCP connection to `port` on `host`. If `host` is omitted,
`'localhost'` will be assumed. `'localhost'` will be assumed.
The `connectListener` parameter will be added as an listener for the The `connectListener` parameter will be added as an listener for the
['connect'](#event_connect_) event. ['connect'](#event_connect_) event.
### net.connect(path, [connectListener]) ## net.connect(path, [connectListener])
### net.createConnection(path, [connectListener]) ## net.createConnection(path, [connectListener])
Creates unix socket connection to `path`. Creates unix socket connection to `path`.
The `connectListener` parameter will be added as an listener for the The `connectListener` parameter will be added as an listener for the
['connect'](#event_connect_) event. ['connect'](#event_connect_) event.
--- ## Class: net.Server
### net.Server
This class is used to create a TCP or UNIX 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. 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 Begin accepting connections on the specified `port` and `host`. If the
`host` is omitted, the server will accept connections directed to any `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) (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`. 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 the last parameter `listeningListener` will be added as an listener for the
['listening'](#event_listening_) event. ['listening'](#event_listening_) event.
#### server.close([cb]) ### server.close([cb])
Stops the server from accepting new connections. This function is Stops the server from accepting new connections. This function is
asynchronous, the server is finally closed when the server emits a `'close'` 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. 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. 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. 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. 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 Set this property to reject connections when the server's connection count gets
high. high.
#### server.connections ### server.connections
The number of concurrent connections on the server. The number of concurrent connections on the server.
`net.Server` is an `EventEmitter` with the following events: `net.Server` is an `EventEmitter` with the following events:
#### Event: 'listening' ### Event: 'listening'
`function () {}` `function () {}`
Emitted when the server has been bound after calling `server.listen`. Emitted when the server has been bound after calling `server.listen`.
#### Event: 'connection' ### Event: 'connection'
`function (socket) {}` `function (socket) {}`
Emitted when a new connection is made. `socket` is an instance of Emitted when a new connection is made. `socket` is an instance of
`net.Socket`. `net.Socket`.
#### Event: 'close' ### Event: 'close'
`function () {}` `function () {}`
Emitted when the server closes. Emitted when the server closes.
#### Event: 'error' ### Event: 'error'
`function (exception) {}` `function (exception) {}`
Emitted when an error occurs. The `'close'` event will be called directly Emitted when an error occurs. The `'close'` event will be called directly
following this event. See example in discussion of `server.listen`. following this event. See example in discussion of `server.listen`.
--- ## Class: net.Socket
### net.Socket
This object is an abstraction of a TCP or UNIX socket. `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 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 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. 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. Construct a new socket object.
@ -245,8 +241,8 @@ Construct a new socket object.
specified underlying protocol. It can be `'tcp4'`, `'tcp6'`, or `'unix'`. specified underlying protocol. It can be `'tcp4'`, `'tcp6'`, or `'unix'`.
About `allowHalfOpen`, refer to `createServer()` and `'end'` event. About `allowHalfOpen`, refer to `createServer()` and `'end'` event.
#### socket.connect(port, [host], [connectListener]) ### socket.connect(port, [host], [connectListener])
#### socket.connect(path, [connectListener]) ### socket.connect(path, [connectListener])
Opens the connection for a given socket. If `port` and `host` are given, 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, 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. ['connect'](#event_connect_) event.
#### socket.bufferSize ### socket.bufferSize
`net.Socket` has the property that `socket.write()` always works. This is to `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 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()`. "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 Sets the encoding (either `'ascii'`, `'utf8'`, or `'base64'`) for data that is
received. Defaults to `null`. 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 Sends data on the socket. The second parameter specifies the encoding in the
case of a string--it defaults to UTF8 encoding. 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 The optional `callback` parameter will be executed when the data is finally
written out - this may not be immediately. 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 Half-closes the socket. i.e., it sends a FIN packet. It is possible the
server will still send some data. 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 If `data` is specified, it is equivalent to calling
`socket.write(data, encoding)` followed by `socket.end()`. `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 Ensures that no more I/O activity happens on this socket. Only necessary in
case of errors (parse error or so). case of errors (parse error or so).
#### socket.pause() ### socket.pause()
Pauses the reading of data. That is, `'data'` events will not be emitted. Pauses the reading of data. That is, `'data'` events will not be emitted.
Useful to throttle back an upload. Useful to throttle back an upload.
#### socket.resume() ### socket.resume()
Resumes reading after a call to `pause()`. 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 Sets the socket to timeout after `timeout` milliseconds of inactivity on
the socket. By default `net.Socket` do not have a timeout. 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 The optional `callback` parameter will be added as a one time listener for the
`'timeout'` event. `'timeout'` event.
#### socket.setNoDelay([noDelay]) ### socket.setNoDelay([noDelay])
Disables the Nagle algorithm. By default TCP connections use the Nagle Disables the Nagle algorithm. By default TCP connections use the Nagle
algorithm, they buffer data before sending it off. Setting `true` for algorithm, they buffer data before sending it off. Setting `true` for
`noDelay` will immediately fire off data each time `socket.write()` is called. `noDelay` will immediately fire off data each time `socket.write()` is called.
`noDelay` defaults to `true`. `noDelay` defaults to `true`.
#### socket.setKeepAlive([enable], [initialDelay]) ### socket.setKeepAlive([enable], [initialDelay])
Enable/disable keep-alive functionality, and optionally set the initial Enable/disable keep-alive functionality, and optionally set the initial
delay before the first keepalive probe is sent on an idle socket. 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 initialDelay will leave the value unchanged from the default
(or previous) setting. Defaults to `0`. (or previous) setting. Defaults to `0`.
#### socket.address() ### socket.address()
Returns the bound address and port of the socket as reported by the operating Returns the bound address and port of the socket as reported by the operating
system. Returns an object with two properties, e.g. system. Returns an object with two properties, e.g.
`{"address":"192.168.57.1", "port":62053}` `{"address":"192.168.57.1", "port":62053}`
#### socket.remoteAddress ### socket.remoteAddress
The string representation of the remote IP address. For example, The string representation of the remote IP address. For example,
`'74.125.127.100'` or `'2001:4860:a005::68'`. `'74.125.127.100'` or `'2001:4860:a005::68'`.
#### socket.remotePort ### socket.remotePort
The numeric representation of the remote port. For example, The numeric representation of the remote port. For example,
`80` or `21`. `80` or `21`.
#### socket.bytesRead ### socket.bytesRead
The amount of received bytes. The amount of received bytes.
#### socket.bytesWritten ### socket.bytesWritten
The amount of bytes sent. The amount of bytes sent.
`net.Socket` instances are EventEmitters with the following events: `net.Socket` instances are EventEmitters with the following events:
#### Event: 'connect' ### Event: 'connect'
`function () { }` `function () { }`
Emitted when a socket connection is successfully established. Emitted when a socket connection is successfully established.
See `connect()`. See `connect()`.
#### Event: 'data' ### Event: 'data'
`function (data) { }` `function (data) { }`
@ -402,7 +398,7 @@ information.)
Note that the __data will be lost__ if there is no listener when a `Socket` Note that the __data will be lost__ if there is no listener when a `Socket`
emits a `'data'` event. emits a `'data'` event.
#### Event: 'end' ### Event: 'end'
`function () { }` `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. caveat that the user is required to `end()` their side now.
#### Event: 'timeout' ### Event: 'timeout'
`function () { }` `function () { }`
@ -425,7 +421,7 @@ the socket has been idle. The user must manually close the connection.
See also: `socket.setTimeout()` See also: `socket.setTimeout()`
#### Event: 'drain' ### Event: 'drain'
`function () { }` `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()` See also: the return values of `socket.write()`
#### Event: 'error' ### Event: 'error'
`function (exception) { }` `function (exception) { }`
Emitted when an error occurs. The `'close'` event will be called directly Emitted when an error occurs. The `'close'` event will be called directly
following this event. following this event.
#### Event: 'close' ### Event: 'close'
`function (had_error) { }` `function (had_error) { }`
Emitted once the socket is fully closed. The argument `had_error` is a boolean 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. 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, 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. 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. 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. Returns true if input is a version 6 IP address, otherwise returns false.

Write Preview
Loading…
Cancel
Save