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

Various changes to Net Documentation, ammended style for API.

v0.7.4-release
Micheil Smith 14 years ago
committed by Ryan Dahl
parent
589e27948b
commit
17595b5343
3 changed files with 181 additions and 154 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. 2
      doc/api/_toc.markdown
  2. 323
      doc/api/net.markdown
  3. 4
      doc/api_assets/style.css

2
doc/api/_toc.markdown
View File

@ -6,9 +6,7 @@
* [Modules](modules.html) * [Modules](modules.html)
* [C/C++ Addons](addons.html) * [C/C++ Addons](addons.html)
* [Process](process.html) * [Process](process.html)
* [Constants](constants.html)
* [Utilities](util.html) * [Utilities](util.html)
* [FreeList](freelist.html)
* [Events](events.html) * [Events](events.html)
* [Buffers](buffers.html) * [Buffers](buffers.html)
* [Streams](streams.html) * [Streams](streams.html)

323
doc/api/net.markdown
View File

@ -1,4 +1,32 @@
## net.Server ## net
The `net` module provides you with an asynchronous network wrapper. It contains
methods for creating both servers and clients (called streams).
### net.createServer(connectionListener)
Creates a new TCP server. The `connectionListener` argument is
automatically set as a listener for the `'connection'` event.
### net.createConnection(arguments...)
Construct a new stream object and opens a stream to the given location. When
the stream is established the `'connect'` event will be emitted.
The arguments for this method change the type of connection:
* `net.createConnection(port, [host])`
Creates a TCP connection to `port` on `host`. If `host` is omitted, `localhost`
will be assumed.
* `net.createConnection(path)`
Creates unix socket connection to `path`
---
### net.Server
This class is used to create a TCP or UNIX server. This class is used to create a TCP or UNIX server.
@ -28,27 +56,7 @@ changed to
This is an `EventEmitter` with the following events: This is an `EventEmitter` with the following events:
### Event: 'connection' #### server.listen(port, [host], [callback])
`function (stream) {}`
Emitted when a new connection is made. `stream` is an instance of
`net.Stream`.
### Event: 'close'
`function () {}`
Emitted when the server closes.
### net.createServer(connectionListener)
Creates a new TCP server. The `connectionListener` argument is
automatically set as a listener for the `'connection'` event.
### server.listen(port, [host], [callback])
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
@ -57,56 +65,50 @@ IPv4 address (`INADDR_ANY`).
This function is asynchronous. The last parameter `callback` will be called This function is asynchronous. The last parameter `callback` will be called
when the server has been bound. when the server has been bound.
#### server.listen(path, [callback])
### server.listen(path, [callback])
Start a UNIX socket server listening for connections on the given `path`. Start a UNIX socket server listening for connections on the given `path`.
This function is asynchronous. The last parameter `callback` will be called This function is asynchronous. The last parameter `callback` will be called
when the server has been bound. when the server has been bound.
#### server.listenFD(fd)
### server.listenFD(fd)
Start a server listening for connections on the given file descriptor. Start a server listening for connections on the given file descriptor.
This file descriptor must have already had the `bind(2)` and `listen(2)` system This file descriptor must have already had the `bind(2)` and `listen(2)` system
calls invoked on it. calls invoked on it.
### server.close() #### server.close()
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. event.
### server.maxConnections #### server.maxConnections
Set this property to reject connections when the server's connection count gets high. 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. The number of concurrent connections on the server.
#### Event: 'connection'
## net.isIP `function (stream) {}`
### 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)
Returns true if input is a version 4 IP address, otherwise returns false. Emitted when a new connection is made. `stream` is an instance of
`net.Stream`.
#### Event: 'close'
### net.isIPv6(input) `function () {}`
Returns true if input is a version 6 IP address, otherwise returns false. Emitted when the server closes.
---
## net.Stream ### net.Stream
This object is an abstraction of of a TCP or UNIX socket. `net.Stream` This object is an abstraction of of a TCP or UNIX socket. `net.Stream`
instance implement a duplex stream interface. They can be created by the instance implement a duplex stream interface. They can be created by the
@ -115,181 +117,204 @@ and passed to the user through the `'connection'` event of a server.
`net.Stream` instances are EventEmitters with the following events: `net.Stream` instances are EventEmitters with the following events:
### Event: 'connect' #### stream.connect(port, [host])
#### stream.connect(path)
`function () { }` Opens the connection for a given stream. If `port` and `host` are given,
then the stream will be opened as a TCP stream, if `host` is omitted,
`localhost` will be assumed. If a `path` is given, the stream will be
opened as a unix socket to that path.
Emitted when a stream connection successfully is established. Normally this method is not needed, as `net.createConnection` opens the
See `connect()`. stream. Use this only if you are implementing a custom Stream or if a
Stream is closed and you want to reuse it to connect to another server.
### Event: 'secure'
`function () { }`
Emitted when a stream connection successfully establishes an SSL handshake with its peer.
This function is asynchronous. When the `'connect'` event is emitted the
stream is established. If there is a problem connecting, the `'connect'`
event will not be emitted, the `'error'` event will be emitted with
the exception.
### Event: 'data'
`function (data) { }` #### stream.setEncoding(encoding=null)
Emitted when data is received. The argument `data` will be a `Buffer` or Sets the encoding (either `'ascii'`, `'utf8'`, or `'base64'`) for data that is
`String`. Encoding of data is set by `stream.setEncoding()`. received.
(See the section on `Readable Stream` for more information.)
### Event: 'end' #### stream.setSecure([credentials])
`function () { }` Enables SSL support for the stream, with the crypto module credentials specifying
the private key and certificate of the stream, and optionally the CA certificates
for use in peer authentication.
Emitted when the other end of the stream sends a FIN packet. If the credentials hold one ore more CA certificates, then the stream will request
for the peer to submit a client certificate as part of the SSL connection handshake.
The validity and content of this can be accessed via verifyPeer() and getPeerCertificate().
By default (`allowHalfOpen == false`) the stream will destroy its file #### stream.verifyPeer()
descriptor once it has written out its pending write queue. However, by
setting `allowHalfOpen == true` the stream will not automatically `end()`
its side allowing the user to write arbitrary amounts of data, with the
caviot that the user is required to `end()` thier side now. In the
`allowHalfOpen == true` case after `'end'` is emitted the `readyState` will
be `'writeOnly'`.
Returns true or false depending on the validity of the peers's certificate in the
context of the defined or default list of trusted CA certificates.
### Event: 'timeout' #### stream.getPeerCertificate()
`function () { }` Returns a JSON structure detailing the peer's certificate, containing a dictionary
with keys for the certificate 'subject', 'issuer', 'valid\_from' and 'valid\_to'
Emitted if the stream times out from inactivity. This is only to notify that #### stream.write(data, encoding='ascii')
the stream has been idle. The user must manually close the connection.
See also: `stream.setTimeout()` Sends data on the stream. The second parameter specifies the encoding in
the case of a string--it defaults to ASCII because encoding to UTF8 is rather
slow.
Returns `true` if the entire data was flushed successfully to the kernel
buffer. Returns `false` if all or part of the data was queued in user memory.
`'drain'` will be emitted when the buffer is again free.
### Event: 'drain' #### stream.end([data], [encoding])
`function () { }` Half-closes the stream. I.E., it sends a FIN packet. It is possible the
server will still send some data. After calling this `readyState` will be
`'readOnly'`.
Emitted when the write buffer becomes empty. Can be used to throttle uploads. If `data` is specified, it is equivalent to calling `stream.write(data, encoding)`
followed by `stream.end()`.
### Event: 'error' #### stream.destroy()
`function (exception) { }` Ensures that no more I/O activity happens on this stream. Only necessary in
case of errors (parse error or so).
Emitted when an error occurs. The `'close'` event will be called directly #### stream.pause()
following this event.
### Event: 'close' Pauses the reading of data. That is, `'data'` events will not be emitted.
Useful to throttle back an upload.
`function (had_error) { }` #### stream.resume()
Emitted once the stream is fully closed. The argument `had_error` is a boolean which says if Resumes reading after a call to `pause()`.
the stream was closed due to a transmission
error.
#### stream.setTimeout(timeout)
### net.createConnection(port, host='127.0.0.1') Sets the stream to timeout after `timeout` milliseconds of inactivity on
the stream. By default `net.Stream` do not have a timeout.
Construct a new stream object and opens a stream to the specified `port` When an idle timeout is triggered the stream will receive a `'timeout'`
and `host`. If the second parameter is omitted, localhost is assumed. event but the connection will not be severed. The user must manually `end()`
or `destroy()` the stream.
When the stream is established the `'connect'` event will be emitted. If `timeout` is 0, then the existing idle timeout is disabled.
### stream.connect(port, host='127.0.0.1') #### stream.setNoDelay(noDelay=true)
Opens a stream to the specified `port` and `host`. `createConnection()` Disables the Nagle algorithm. By default TCP connections use the Nagle
also opens a stream; normally this method is not needed. Use this only if algorithm, they buffer data before sending it off. Setting `noDelay` will
a stream is closed and you want to reuse the object to connect to another immediately fire off data each time `stream.write()` is called.
server.
This function is asynchronous. When the `'connect'` event is emitted the #### stream.setKeepAlive(enable=false, [initialDelay])
stream is established. If there is a problem connecting, the `'connect'`
event will not be emitted, the `'error'` event will be emitted with
the exception.
Enable/disable keep-alive functionality, and optionally set the initial
delay before the first keepalive probe is sent on an idle stream.
Set `initialDelay` (in milliseconds) to set the delay between the last
data packet received and the first keepalive probe. Setting 0 for
initialDelay will leave the value unchanged from the default
(or previous) setting.
### stream.remoteAddress #### stream.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'`.
This member is only present in server-side connections. This member is only present in server-side connections.
### stream.readyState #### stream.readyState
Either `'closed'`, `'open'`, `'opening'`, `'readOnly'`, or `'writeOnly'`. Either `'closed'`, `'open'`, `'opening'`, `'readOnly'`, or `'writeOnly'`.
### stream.setEncoding(encoding=null) #### Event: 'connect'
Sets the encoding (either `'ascii'`, `'utf8'`, or `'base64'`) for data that is `function () { }`
received.
### stream.setSecure([credentials]) Emitted when a stream connection successfully is established.
See `connect()`.
Enables SSL support for the stream, with the crypto module credentials specifying the private key and certificate of the stream, and optionally the CA certificates for use in peer authentication.
If the credentials hold one ore more CA certificates, then the stream will request for the peer to submit a client certificate as part of the SSL connection handshake. The validity and content of this can be accessed via verifyPeer() and getPeerCertificate(). #### Event: 'secure'
### stream.verifyPeer() `function () { }`
Returns true or false depending on the validity of the peers's certificate in the context of the defined or default list of trusted CA certificates. Emitted when a stream connection successfully establishes an SSL handshake with its peer.
### stream.getPeerCertificate()
Returns a JSON structure detailing the peer's certificate, containing a dictionary with keys for the certificate 'subject', 'issuer', 'valid\_from' and 'valid\_to' #### Event: 'data'
### stream.write(data, encoding='ascii') `function (data) { }`
Sends data on the stream. The second parameter specifies the encoding in Emitted when data is received. The argument `data` will be a `Buffer` or
the case of a string--it defaults to ASCII because encoding to UTF8 is rather `String`. Encoding of data is set by `stream.setEncoding()`.
slow. (See the section on `Readable Stream` for more information.)
Returns `true` if the entire data was flushed successfully to the kernel #### Event: 'end'
buffer. Returns `false` if all or part of the data was queued in user memory.
`'drain'` will be emitted when the buffer is again free.
### stream.end([data], [encoding]) `function () { }`
Half-closes the stream. I.E., it sends a FIN packet. It is possible the Emitted when the other end of the stream sends a FIN packet.
server will still send some data. After calling this `readyState` will be
`'readOnly'`.
If `data` is specified, it is equivalent to calling `stream.write(data, encoding)` By default (`allowHalfOpen == false`) the stream will destroy its file
followed by `stream.end()`. descriptor once it has written out its pending write queue. However, by
setting `allowHalfOpen == true` the stream will not automatically `end()`
its side allowing the user to write arbitrary amounts of data, with the
caveat that the user is required to `end()` their side now. In the
`allowHalfOpen == true` case after `'end'` is emitted the `readyState` will
be `'writeOnly'`.
### stream.destroy()
Ensures that no more I/O activity happens on this stream. Only necessary in #### Event: 'timeout'
case of errors (parse error or so).
### stream.pause() `function () { }`
Pauses the reading of data. That is, `'data'` events will not be emitted. Emitted if the stream times out from inactivity. This is only to notify that
Useful to throttle back an upload. the stream has been idle. The user must manually close the connection.
### stream.resume() See also: `stream.setTimeout()`
Resumes reading after a call to `pause()`.
### stream.setTimeout(timeout) #### Event: 'drain'
Sets the stream to timeout after `timeout` milliseconds of inactivity on `function () { }`
the stream. By default `net.Stream` do not have a timeout.
When an idle timeout is triggered the stream will receive a `'timeout'` Emitted when the write buffer becomes empty. Can be used to throttle uploads.
event but the connection will not be severed. The user must manually `end()`
or `destroy()` the stream.
If `timeout` is 0, then the existing idle timeout is disabled. #### Event: 'error'
### stream.setNoDelay(noDelay=true) `function (exception) { }`
Disables the Nagle algorithm. By default TCP connections use the Nagle Emitted when an error occurs. The `'close'` event will be called directly
algorithm, they buffer data before sending it off. Setting `noDelay` will following this event.
immediately fire off data each time `stream.write()` is called.
### stream.setKeepAlive(enable=false, [initialDelay]) #### Event: 'close'
`function (had_error) { }`
Emitted once the stream is fully closed. The argument `had_error` is a boolean which says if
the stream was closed due to a transmission
error.
---
### 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)
Returns true if input is a version 4 IP address, otherwise returns false.
#### net.isIPv6(input)
Returns true if input is a version 6 IP address, otherwise returns false.
Enable/disable keep-alive functionality, and optionally set the initial
delay before the first keepalive probe is sent on an idle stream.
Set `initialDelay` (in milliseconds) to set the delay between the last
data packet received and the first keepalive probe. Setting 0 for
initialDelay will leave the value unchanged from the default
(or previous) setting.

4
doc/api_assets/style.css
View File

@ -115,6 +115,10 @@ h4 {
margin: 2.2em 0 1.25em; margin: 2.2em 0 1.25em;
} }
h4 + h4 {
margin: 0 0 1.25em;
}
h5 { h5 {
font-size: 1.125em; font-size: 1.125em;
line-height: 1.4em; line-height: 1.4em;

Write Preview
Loading…
Cancel
Save