Socket

An advanced non-blocking socket class.

Nidium Socket API was designed to connect to:

  • any host:port as a client
  • to listen to a port as a server to handle incomming client connections.

The underlying system is powered by a powerful, non-blocking event-driven engine.

//Client Example
var socket = new Socket("nidium.com", 80).connect();
socket.onconnect = function() {
    this.write("GET / HTTP/1.1\n");
    this.write("Host: www.nidium.com\n\n");
}
socket.ondisconnect = function() {
    console.log("Disconnected");
}
socket.onread = function(data) {
    //console.log("=>", data);
}
//Server example
var socket = new Socket("0.0.0.0", 8000).listen();
socket.onaccept = function(clientSocket) {
    clientSocket.write("Hello");
}
socket.ondisconnect = function(clientSocket) {
    console.log("Client Disconnected");
}
socket.onread = function(clientSocket, data) {
    //console.log("=>", data);
}

new Socket(host, port)

Create a new Socket object ready for connecting or listening.

Arguments:
host (String)

Hostname or ip-address. '0.0.0.0' as host means any host when used with 'listen()' (e.g. when the socket must be accessed from the Internet). If an name is given, the name is resolved asynchronously automatic.

port (Integer)

port number

close()

Close a socket connection.

connect([mode=t])

Starts a client.

Connect the socket to the tuple host and port that were specified in the constructor.

Arguments:
mode (String)

Conncection mode. Allowed values are: 'tcp'|'udp'|'ssl'|'unix'|'tcp-lz4'

Returns: Socket

The socket, for chaining

listen([mode=t])

Starts a server.

The server will listen to the host and port that were specified in the constructor.

Arguments:
mode (String)

Connection mode. Allowed values are: 'tcp'|'udp'|'ssl'|'unix'|'tcp-lz4'

Returns: Socket

The socket, for chaining

sendTo(ip, port, data)

Send data from a socket server to a client via udp.

Arguments:
ip (String)

The Ip to send to

port (Integer)

Portnumber

data

(String | ArrayBuffer): The data to send

write(data)

Write data.

Arguments:
data

(String | ArrayBuffer): data to send

Returns: Integer

bytes written

binary

  • Type: Boolean

Get or set the binary mode for send/receive data.

When the 'Socket.binary' property is set to 'true', the 'Socket.ondata' event will be called with an 'ArrayBuffer' instead of a 'string'.

var socket = new Socket("0.0.0.0", 8001).listen()
socket.binary = true;
socket.onread = function(clientSocket, data) {
    console.log("=>", data); // data is an ArrayBuffer
}

encoding

  • Type: String

The encoding to read non-binary data.

When the 'Socket.binary' property is set to 'false' (its default value), the 'Socket.encoding' property defines the encoding of received data. Allowed values are 'undefined'|'ASCII'|'utf8'.

var socket = new Socket("127.0.0.1", 6667).connect();
socket.binary = false;
socket.encoding = 'utf8';
// if the server sends something like :
socket.onread = function(data) {
    console.log("=>", data);
}

readline

  • Type: Boolean

Handle 'Socket.onread' events on a one line-per-line basis. A TCP Socket stream is 'frameless'.

A TCP Socket stream is 'frameless'. When you receive data, there is no concept of boundaries. For instance, if an endpoint sends "hello" it doesn't mean you can't receive the data in 2 or more callbacks. The 'readline' property tells the socket to set boundaries around the newline char (\n). This is particularly useful to design simple protocols like IRC which are line-based.

The maximum length of a line is internally set to 8192 bytes.

var socket = new Socket("irc.freenode.org", 6667).connect();
socket.readline = true;
socket.onconnect = function(clientSocket) {
    clientSocket.write("NICKNAME foo\n");
    clientSocket.write("USER A A A A\n");
}
// if the server sends something like :
// HELLO\nPING 123\nFOOBAR, the "onread" callback is called twice (once with HELLO and once with PING).
// The remaining data (FOOBAR) is held in memory until a "\n" is encountered.
socket.onread = function(data) {
    console.log("=>", data);
}

timeout

  • Type: Integer

Get or set the timeout on a socket connection.

Event: onaccept(clientSocket)

Function to execute on a server when a client connects.

Parameters:
clientSocket (SocketClient)

Socketclient instance

Event: onconnect()

Function to execute on a socket if client called connect and the connection has been established correctly.

This method is called when a new client connects on a listening Socket.

Event: ondisconnect(client)

Function to execute on a socket upon the disconnect event.

Parameters:
client (SocketClient)

Socketclient instance

Event: ondrain()

Function to execute on a socket if it has been drained.

That is: after a 'Socket.write' call, when everything was written, and the socket is ready for writing again.

Event: onmessage(data, details)

Function to execute when a message is available on a 'udp' socket.

Parameters:
data (String)

The message

details (Object)

Connection details object

ip (String)

The remote IP address

port (Integer)

The connected port

Event: onread(data)

Function to execute on a socket upon the read event.

Parameters:
data (String)

The message


Caught a mistake or want to contribute to the documentation? Edit this page on GitHub!