Using the SashXB Communications Extension

SashXB supports several types of network sockets. You can send and receive UDP datagrams with a DatagramSocket, listen for and respond to TCP connections with a ServerSocket, or send and receive data with a TCP ClientSocket.

Sash.Comm
Sash.Comm.Sockets
Sash.Comm.DatagramSocket
Sash.Comm.ClientSocket
Sash.Comm.ServerSocket

1. Sash.Comm

sashISockets Sockets Accesses Sockets, which can be used to create new socket objects.

2. Sash.Comm.Sockets

Constructors
DatagramSocket	Creates a DatagramSocket object, which can be used to exchange UDP datagrams with remote hosts.
ClientSocket	Creates a ClientSocket object, which can be used to initiate and maintain TCP/IP stream connections to remote hosts.
ServerSocket	Creates a ServerSocket object, which can be used to listen for and accept incoming TCP/IP stream connections from remote hosts.
Properties
`readonly string` LocalHostname	Returns the local host name.
Methods
`array` ResolveHostName(`string` hostname)	Resolves a DNS hostname into one or more dotted-decimal IP address(es), returning the addresses as an array of strings.
`string` ResolveHostNameFirst(`string` hostname)	Resolves a DNS hostname into one or more dotted-decimal IP address(es), returns the only the first IP address as a string.

3. Sash.Comm.Sockets.DatagramSocket

DatagramSocket is used to exchange short individual chunks of data (called datagrams) with other hosts. Unlike TCP/IP sockets, DatagramSockets do not need to be connected to the remote hosts before sending and receiving data. However, each datagram is limited in size, and there is no guarantee that separate datagrams sent in a certain order will arrive in that order.

Event

Receiver prototype

Description

OnClosed
handler(sashIDatagramSocket dsocket)
Fired when the socket has been completely deinitialized following a call to Close. Called with the datagram socket that was closed.

OnReceived
handler(sashIDatagramSocket dsocket, string data)
Fired when a datagram is received from a remote host. Called with the datagram socket that received the data, as well as the actual data that was received.

OnSendError
handler(sashIDatagramSocket dsocket, string data)
Fired when an error occurs while attempting to send a datagram. Called with the datagram socket that was attempting to send as well as the data that it was trying to send.

Properties

JSContext Context
A storage property for any user-defined value or object.

readonly string LastErrorDescription
A string description of the last error to occur on the socket. If an OnSendError event occurs, this property will contain a message explaining what happened to the socket.

readonly long MaxDatagramSize
Specifies the maximum allowable amount of data in bytes that can be sent in a single datagram.

readonly long ReceivePort
Specifies the local port on which the datagram socket is listening for incoming data.

Methods

void Close([boolean bForce])
Closes the socket, so that it no longer sends or receives datagrams. If bForce is true, close the socket immediately, otherwise allow all queued datagrams to be sent. NOTE: bForce is ignored.

boolean Create([long Port])
Creates the datagram socket, enabling send operations and associating it with a local port for receive operations (If the port isn't specified, then one will be assigned).No data can be sent via SendDatagram or received on a DatagramSocket until Create is called and returns successfully.

void SendDatagram(string vData, string strDestAddress, long nDestPort)
Buffers a datagram (with contents vData) for transmission to a remote host (specified by a hostname and port number).

void SendConnectionlessDatagram(string vData, string strDestAddress, long nDestPort)
Buffers a datagram (with contents vData) for transmission to a remote host (specified by a hostname and port number). The DatagramSocket does not need to be connected.

Example:


function on_received(socket, data){
		print ("Data received: " + data);
}

var dsocket = new Sash.Comm.Sockets.DatagramSocket();
dsocket.OnReceived = "on_received";

// Listen on port 8888. If any datagrams are sent to this port, 
// their contents will be printed out by 'on_received'..
dsocket.Create(8888);

4. Sash.Comm.Sockets.ClientSocket

A ClientSocket object represents a TCP/IP stream socket. It is used to connect to and exchange data with remote servers.

Event

Receiver prototype

Description

OnClosed
handler(sashIClientSocket csocket)
Fired when the connection is closed by a call to the Close method or terminated by the remote host.

OnConnect
handler(sashIClientSocket csocket)
Fired when a connection attempt that was initiated using the Connect method is successfully established.

OnError
handler(sashIClientSocket csocket)
Fired when an error occurs during a socket operation. Check the LastErrorDescription for a short explanation of what happened.

OnReceived
handler(sashIClientSocket csocket)
Fired when data is received from the remote host.

Properties

JSContext Context
A storage property for any user-defined value or object.

readonly string LastErrorDescription
A string description of the last error to occur on the socket. If an OnError event occurs, this property will contain a message explaining what happened to the socket.

readonly boolean Connected
Specifies whether the socket is currently connected to a remote host.

readonly string LocalIPAddress
Contains the IP address in dotted-decimal format of the local system over which the socket is connected.

readonly string RemoteHost
Specifies the IP address in dotted-decimal format of the host to which the socket is connected in dotted-decimal string format.

readonly long PendingReceiveByteCount
Specifies the amount of data in bytes that can be immediately retrieved using the Receive method.

readonly long PendingSendByteCount
Specifies the amount of data in bytes that has been buffered for transmission by a call to Send but has not yet actually been transmitted.

long ReceivedByteCount
Specifies the total amount of data in bytes that has been received on the socket (Can be reset to any value at any time).

long SentByteCount
Specifies the total amount of data in bytes that has been transmitted on the socket (Can be reset to any value at any time).

Methods

boolean Connect(string remoteHost, long remotePort, [string socksHost, [long socksPort])
Begins a connection attempt to the remote server. NOTE: socks parameters are ignored.

string Receive([boolean bReceiveAsBinary, [long nBytesToReceive])
Receives data on a connected socket. It is strongly recommended that Receive be used only in the context of OnReceived or OnClosed events. bReceiveAsBinary is ignored. If nBytesToReceive is not specified, then all data in the buffer will be read.

long SearchPendingReceiveDat(string searchFor)
SearchPendingReceiveData is used to search the buffer of received data for a string without first having to copy it into a local variable.

boolean Send(string vData)
Transmits data on a connected socket.

void Close([boolean bForce])
Closes an active connection. If bForce is true, close the socket immediately, otherwise allow all queued datagrams to be sent.

Example:


function on_received(socket){
	var data = socket.Receive();
	print ("Data received: " + data);
}

function on_connect(socket){
	socket.Send("GET index.html HTTP/1.0\r\n");
}

var csocket = new Sash.Comm.Sockets.ClientSocket();
csocket.OnReceived = "on_received";
csocket.OnConnect = "on_connect";
csocket.Connect("www.cnn.com", 80);

5. Sash.Comm.Sockets.ServerSocket

ServerSocket is used to listen for incoming TCP/IP stream connections from remote clients. Once a connection is received, the weblication can communicate with the remote machine using a ClientSocket object.

Event

Receiver prototype

Description

OnConnection
handler(sashIServerSocket ssocket)
Fired when an incoming connection is received.

OnError
handler(sashIServerSocket ssocket)
Fired on an error. Check the LastErrorDescription for a short explanation of what happened.

Properties

JSContext Context
A storage property for any user-defined value or object.

readonly string LastErrorDescription
A string description of the last error to occur on the socket. If an OnError event occurs, this property will contain a message explaining what happened to the socket.

readonly long ServerPort
Specifies the port on which the server is listening for connections.

readonly boolean Started
Specifies whether the server is actively listening for connections.

Methods

boolean AcceptConnection(sashIClientSocket clientObj)
Accepts an incoming connection. AcceptConnection should only be called within the context of an OnConnection event.

boolean Start([long Port])
Begins listening for connections on the specified port.

void Stop()
Stops listening for connections.


function on_received(socket){
	var data = socket.Receive();
	print ("Data received: " + data);
}

function on_connection(socket){
	var csocket = new Sash.Comm.Sockets.ClientSocket();
	// Set csocket properties here.

	ssocket.AcceptConnection(csocket);
}

var ssocket = new Sash.Comm.Sockets.ServerSocket();
ssocket.OnConnection = "on_connection";

// Start listening for connections on port 8888.
ssocket.Start(8888);

Wing Yung

Last modified: Wed Apr 3 18:02:22 EST 2002

Event	Receiver prototype	Description
OnClosed	handler(`sashIDatagramSocket` dsocket)	Fired when the socket has been completely deinitialized following a call to Close. Called with the datagram socket that was closed.
OnReceived	handler(`sashIDatagramSocket` dsocket, `string` data)	Fired when a datagram is received from a remote host. Called with the datagram socket that received the data, as well as the actual data that was received.
OnSendError	handler(`sashIDatagramSocket` dsocket, `string` data)	Fired when an error occurs while attempting to send a datagram. Called with the datagram socket that was attempting to send as well as the data that it was trying to send.

Properties
`JSContext` Context	A storage property for any user-defined value or object.
`readonly string` LastErrorDescription	A string description of the last error to occur on the socket. If an OnSendError event occurs, this property will contain a message explaining what happened to the socket.
`readonly long` MaxDatagramSize	Specifies the maximum allowable amount of data in bytes that can be sent in a single datagram.
`readonly long` ReceivePort	Specifies the local port on which the datagram socket is listening for incoming data.
Methods
`void` Close([`boolean` bForce])	Closes the socket, so that it no longer sends or receives datagrams. If bForce is true, close the socket immediately, otherwise allow all queued datagrams to be sent. NOTE: bForce is ignored.
`boolean` Create([`long` Port])	Creates the datagram socket, enabling send operations and associating it with a local port for receive operations (If the port isn't specified, then one will be assigned).No data can be sent via SendDatagram or received on a DatagramSocket until Create is called and returns successfully.
`void` SendDatagram(`string` vData, `string` strDestAddress, `long` nDestPort)	Buffers a datagram (with contents vData) for transmission to a remote host (specified by a hostname and port number).
`void` SendConnectionlessDatagram(`string` vData, `string` strDestAddress, `long` nDestPort)	Buffers a datagram (with contents vData) for transmission to a remote host (specified by a hostname and port number). The DatagramSocket does not need to be connected.