From cf0eebf68545d09330e6ba101b82f62beee62543 Mon Sep 17 00:00:00 2001 From: Ryan Date: Tue, 26 May 2009 15:20:25 +0200 Subject: [PATCH] Add preliminary tcp documentation --- website/{node.html => index.html} | 180 +++++++++++++++++++++++++++++++++----- 1 file changed, 157 insertions(+), 23 deletions(-) rename website/{node.html => index.html} (78%) diff --git a/website/node.html b/website/index.html similarity index 78% rename from website/node.html rename to website/index.html index 7095c3f..2833245 100644 --- a/website/node.html +++ b/website/index.html @@ -43,6 +43,7 @@ h1 a { color: inherit; } pre, code { font-family: monospace; font-size: 14pt; + color: #fee; } pre { @@ -267,32 +268,54 @@ node.fs.rename("/tmp/hello", "/tmp/world", function (status) {
node.fs.rename(path1, path2, on_completion(status))
-
- rename(2) -
+
rename(2)
node.fs.stat(path, on_completion(status, stats))
-
- stat(2) -
+
stat(2)
node.fs.unlink(path, on_completion(status))
-
- unlink(2) -
+
unlink(2)
node.fs.rmdir(path, on_completion(status))
-
- rmdir(2) +
rmdir(2)
+ +
node.fs.close(fd, on_completion(status))
+
close(2)
+ +
node.fs.open(path, flags, mode, on_completion(status, fd))
+
open(2) +

The constants like O_CREAT are defined at node.fs.O_CREAT. +

+ +
node.fs.write(fd, data, position, on_completion(status, written))
+
Write data to the file specified by fd. +

data is either an array of integer (for raw data) or a string + for UTF-8 encoded characters. +

position refers to the offset from the beginning of the + file where this data should be written. If null, the data + will be written at the current position. + +

See also pwrite(2) +

+
node.fs.read(fd, length, position, encoding, on_completion(status, data))
+
Read data from the file specified by fd. + +

length is an integer specifying the number of bytes to read. + +

position is an integer specifying where to begin reading + from in the file. + +

encoding is either node.fs.UTF8 or + node.fs.RAW. +

node.fs.File

+

Easy buffered file object. +

Internal request queues exist for each file object so that multiple commands can be issued at once without worry that they will be executed out-of-order. Thus the following is safe: @@ -305,7 +328,7 @@ file.write("world"); file.close();

-It's important to understand that the request queues are local to a single file. +Request queues are local to a single file. If one does 

fileA.write("hello");
 fileB.write("world");
@@ -318,10 +341,20 @@ completion callbacks: });
-
new node.fs.File
-
Creates a new file object.
+
new node.fs.File(options={})
+
Creates a new file object. + +

The options argument is optional. It can contain the + following fields +

    +
  • fd — a file descriptor for the file. +
  • encoding — how file.read() should return + data. Either "raw" or "utf8". Defaults to raw. +
+
+ -
file.onError
+
file.onError = function (method, errno, msg) { }
Callback. This is called internally anytime an error occurs with this file. There are three arguments: the method name, the POSIX errno, and a string describing the error. @@ -338,7 +371,7 @@ file.onError = function (method, errno, msg) { file.open(path, "w+") -
file.open(path, mode, on_completion)
+
file.open(path, mode, on_completion())
Opens the file at path.

mode is a string: "r" open for reading and writing. @@ -351,20 +384,20 @@ file.open(path, "w+") append to the end of the file. "a+"

The on_completion is a callback that is made without - arguments when the operation completes. It is optional + arguments when the operation completes. It is optional. If an error occurred the on_completion callback will not be called, but the file.onError will be called.

-
file.read(length, position, on_completion)
+
file.read(length, position, on_completion(data))
-
file.write(data, position, on_completion)
+
file.write(data, position, on_completion(written))
-
file.close(on_completion)
+
file.close(on_completion())
@@ -374,8 +407,109 @@ file.open(path, "w+")

node.tcp.Server

+

Here is an example of a echo server which listens for connections on port +7000 +

+function Echo (socket) {
+  socket.setEncoding("utf8");
+  socket.onConnect = function () {
+    socket.send("hello\r\n");
+  };
+  socket.onReceive = function (data) {
+    socket.send(data);
+  };
+  socket.onEOF = function () {
+    socket.send("goodbye\r\n");
+    socket.close();
+  };
+}
+var server = new node.tcp.Server(Echo, {backlog: 1024});
+server.listen(7000, "localhost");
+
+ +
+
new node.tcp.Server(connection_handler(socket), options={});
+
Creates a new TCP server. + +

connection_handler is a callback which is called + on each connection. It is given one argument: an instance of + node.tcp.Connection. + +

options for now only supports one option: + backlog which should be an integer and describes how large of + a connection backlog the operating system should maintain for this server. + The backlog defaults to 1024. +

+ +
server.listen(port, host=null)
+
Tells the server to listen for TCP connections to port + and host. Note, host is optional. If + host is not specified the server will accept connections to + any IP address on the specified port. +
+ +
server.close()
+
Stops the server from accepting new connections.
+
+ +

node.tcp.Connection

+

This object is used as a TCP client and also as a server-side socket for +node.tcp.Servers. + +

+
new node.tcp.Connection()
+
Creates a new connection object. +
+ +
connection.setEncoding(encoding)
+
Sets the encoding (either "utf8" or "raw") + for data that is received. +
+ +
connection.send(data)
+
sends data on the connection +
+ +
connection.close()
+
Half-closes the connection. I.E. sends a FIN packet. It is possible + the server will still send some data. +
+ +
connection.fullClose()
+
Close both ends of the connection. Data that is received after this + call is responded to with RST packets. If you don't know about this, just use + close(). +
+ +
connection.forceClose()
+
Ensures that no more I/O activity happens on this socket. + Only necessary in case of errors (parse error or so). +
+ +
conneciton.onConnect = function () { };
+
Call once the connection is established.
+ +
conneciton.onReceive = function (data) { };
+
Called when data is received on the connection. Encoding of data is + set by connection.setEncoding(). data will + either be a string, in the case of utf8, or an array of integer in the + case of raw encoding.
+ +
conneciton.onEOF = function () { };
+
Called when the other end of the connection sends a FIN packet. + onReceive will not be called after this. + You should probably just call connection.close() in this + callback. + +
conneciton.onDisconnect = function () { };
+
Called once the connection is fully disconnected.
+ +
conneciton.onError = function () { };
+
Called on an error.
+
+

node.http

The HTTP interfaces here are designed to support many features -- 2.7.4