diff options
author | isaacs <i@izs.me> | 2012-02-27 23:09:34 +0400 |
---|---|---|
committer | isaacs <i@izs.me> | 2012-03-01 04:04:52 +0400 |
commit | e8ad5b9c1ca80447039b590d3095c18e45e9731f (patch) | |
tree | 5ce9b2bf1294e5b87519d8987e9b1f922e890848 /doc/api | |
parent | e88a1ba74a6055687ad862a32e82ecd66cbd5e8a (diff) |
doc refactor: net
Diffstat (limited to 'doc/api')
-rw-r--r-- | doc/api/net.markdown | 122 |
1 files changed, 51 insertions, 71 deletions
diff --git a/doc/api/net.markdown b/doc/api/net.markdown index 49cf5b049ce..d3c2bff8b44 100644 --- a/doc/api/net.markdown +++ b/doc/api/net.markdown @@ -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. |