From 2fd5cb3d2e002a2bea9a78bfe7a2d38486289f64 Mon Sep 17 00:00:00 2001 From: isaacs Date: Mon, 27 Feb 2012 11:09:34 -0800 Subject: [PATCH] doc refactor: net --- doc/api/net.markdown | 105 ++++++++++++++++++++----------------------- 1 file changed, 49 insertions(+), 56 deletions(-) diff --git a/doc/api/net.markdown b/doc/api/net.markdown index a857eac29d..7923706567 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(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.