Socket Namespace Reference

wilton/Socket
Networking sockets. More...

Functions
Undefined	close (Function|Undefined callback)
	Close the socket.
String	read (Number length, Function|Undefined callback)
	Read data from the socket.
Object	Socket (Object options, Function|Undefined callback)
	Create and open a networking socket.
Number	writeHex (String data, Function|Undefined callback)
	Write specifed string to the socket.
Number	writePlain (String data, Function|Undefined callback)
	Write specifed string to the socket.

Detailed Description

This module provides access to networking sockets API.

TCP and UDP protocols are supported for both "client" and "server" operations. Implementation uses async IO underneath, but all operations are always done on the caller thread, effectively providing a synchronous API.

Data from network is returned encoded in hexadecimal encoding, use wilton/hex for decoding.

Socket can be closed manually to release system resource, otherwise it will be closed during the shutdown.

Usage example:

// open socket
var socket = new Socket({
    ipAddress: "127.0.0.1",
    tcpPort: 21,
    protocol: "TCP",
    role: "server",
    timeoutMillis: 500
});

// read data from socket
var received = socket.read(42);

// write to socket
socket.writePlain("HELO");

// close socket
socket.close();

Function Documentation

Undefined Socket::close

(

Function|Undefined

callback

)

Closes this socket releasing system resources. Socket left open will be closed on shutdown.

Parameters

callback

Function|Undefined callback to receive result or error

Returns

Undefined

String Socket::read	(	Number	length,
		Function|Undefined	callback
	)

Tries to read a specified amount of data from the socket. Returned result can contain less data than requested. Returns empty string if no data is available and timeout is exceeded.

Uses timeoutMillis parameter (specified in constructor) as a timeout.

Parameters

length	Number amount of the data to read (in bytes)
callback	Function|Undefined callback to receive result or error

Returns

String device response data in hexadecimal encoding, empty string on timeout

Object Socket::Socket	(	Object	options,
		Function|Undefined	callback
	)

Creates a TCP or UDP socket and establishes the networking connection. For client sockets - opens the connection to server. For server sockets - bind to the specified local address and (for TCP) accepts the incoming connection.

Parameters

options	Object configuration object, see possible options below
callback	Function|Undefined callback to receive result or error

Returns

Object Socket instance

Options

• ipAddress String for server - IP address to bind to, for client: address to connect to
• tcpPort Number|Undefined TCP port number
• udpPort Number|Undefined UDP port number
• protocol String networking protocol, supported values: TCP, UDP
• role String socket role, supported values: client, server
• timeoutMillis Number max number of milliseconds allowed to establish the connection

Number Socket::writeHex	(	String	data,
		Function|Undefined	callback
	)

Write specifed string in hexadecimal encoding to socket.

Writes specified hex-string to socket, unlike writePlain() this function may be used to write abritrary (possibly binary) data.

Uses timeoutMillis parameter (specified in constructor) as a timeout.

Parameters

data	String string to write to socket
callback	Function|Undefined callback to receive result or error

Returns

Number number of bytes written to socket

Number Socket::writePlain	(	String	data,
		Function|Undefined	callback
	)

Writes specified string to socket converting the bytes of input string into hexadecimal encoding as-is without changing the UTF-16 encoding. Using this method with non-ASCII symbols may lead to unexpected results.

To write UTF-8 bytes to socket use writeHex() in conjunction with hex.encodeUTF8().

Uses timeoutMillis parameter (specified in constructor) as a timeout.

Parameters

data	String string to write to socket
callback	Function|Undefined callback to receive result or error

Returns

Number number of bytes written to socket