Socket

Module	ejs
Definition	class Socket
Inheritance	Socket Object
Specified	ejscript-2.5
Stability	Prototype.

Client and server side TCP/IP support for IPv4 and IPv6 communications.

This class supports broadcast, datagram and byte-stream socket sevices for both client and server endpoints. Aynchronous and asynchronous operation is supported.

Properties

Qualifiers	Property	Type	Description
get	address	String	Local IP address bound to this socket. Set to the address in dot notation or empty string if it is not bound.
get set	async	Boolean	The current async mode. Set to true if the stream is in async mode.
get set	encoding	String	Current encoding scheme for serializing strings. Defaults to "utf-8".
get	isEof	Boolean	Is the socket at end of input. I.e. Is closed or has the other end sent a FIN packet.
get	port	Number	The port bound to this socket. Set to the integer port number or zero if not bound.
get	remoteAddress	String	The remote address bound to this socket. Set to the remote address in dot notation or empty string if it is not bound.

Inherited Properties

Socket Class Methods

(No own class methods defined)

Qualifiers	Method

Inherited Methods

Socket Instance Methods

Qualifiers	Method
	Socket()
	Create a socket object (.
	accept(): Socket
	Receive a client socket.
	close(): Void
	Close the stream.
	connect(address: Object): Void
	Establish a connection to a client from this socket to the supplied address.
	flush(dir: Number): Void
	Flush the stream and underlying streams.
	listen(address): Void
	Listen on a socket for client connections.
	off(name: Object, observer: Function): Void
	Remove an observer from the stream.
	on(name, observer: Function): Socket
	Add an observer to the stream for the named events.
	read(buffer: ByteArray, offset: Number, count: Number = -1): Number
	Read a data from the stream.
	write(data: Array): Number
	Write data to the stream.

Inherited Methods

Method Detail

Socket()

Description: Create a socket object (.

accept(): Socket

Description: Receive a client socket. Accept must be called after invoking listen.

Returns: A socket connected to the client endpoint. 0.

close(): Void

Description: Close the stream.

Events

A close event is issued before closing the stream.

connect(address: Object): Void

Description: Establish a connection to a client from this socket to the supplied address. After a successful call to connect() the socket may be used for sending and receiving.

Parameters

address: Object

The endpoint address on which to listen. The address can be either a port number, an IP address string, a composite "IP:PORT" string or a port number string. If only a port number is provided, the socket will listen on all interfaces.

Events

Issues

A "writable" event when the connection is complete.

Throws: IOError: if the connection fails. Reasons may include the socket is already bound or the host is unknown.

flush(dir: Number): Void

Description: Flush the stream and underlying streams. A supplied flush direction argument modifies the effect of this call. If direction is set to Stream.READ, then all read data is discarded. If direction is set to Stream.WRITE, any buffered data is written. Stream.BOTH will cause both directions to be flushed. If the stream is in sync mode, this call will block until all data is written. If the stream is in async mode, it will attempt to write all data but will return immediately. Defaults to Stream.WRITE.

Parameters

dir: Number

Direction to flush. Set to READ WRITE or BOTH.

listen(address): Void

Description: Listen on a socket for client connections. This will put the socket into a server role for communcations. If the socket is in sync mode, the listen call will block until a client connection is received after which accept() should be called to receive the socket instance for the new connection. If a the listening socket is in async mode, the listen call will return immediately and client connections will be notified via "accept" events.

Parameters

address

The endpoint address on which to listen. The address can be either a port number, an IP address string or a composite "IP:PORT" string. If only a port number is provided, the socket will listen on all interfaces.

Events

Issues

A "accept" event when there is a new connection available. In response, the accept method should be called.

Throws: ArgError: if the specified listen address is not valid, and IOError for network errors.

off(name: Object, observer: Function): Void

Description: Remove an observer from the stream.

Parameters

name: Object	Event name previously used with observe. The name may be an array of events.
observer: Function	Observer function previously used with observe.

on(name, observer: Function): Socket

Description: Add an observer to the stream for the named events.

Parameters

name: [String\|Array]	Name of the event to listen for. The name may be an array of events.
observer: Function	Callback observer function. The function is called with the following signature: function observer(event: String, ...args): Void.

Events

readable	Issued when the stream becomes readable.
writable	Issued when the stream becomes writable.
close	Issued when stream is being closed. 8.
writable	Issued when the connection is writable to accept body data (PUT, POST).

read(buffer: ByteArray, offset: Number, count: Number = -1): Number

Description: Read a data from the stream. If data is available, the call will return immediately. If no data is available and the stream is in sync mode, the call will block until data is available. If no data is available and the stream is in async mode, the call will not block and will return immediately. In this case a "readable" event will be issued when data is available for reading.

Parameters

buffer: ByteArray	Destination byte array for read data.
offset: Number	Offset in the byte array to place the data. If the offset is -1, then data is appended to the buffer write position which is then updated. If offset is >= 0, the data is read to the offset and the read pointer is set to the offset and the write pointer to one past the end of the data just read.
count: Number	Read up to this number of bytes. If -1, read as much as the buffer will hold up. If the stream is of fixed and known length (such as a file) and the buffer is of sufficient size or is growable, read the entire stream. If the buffer is of a fixed size, ready only what will fit into the buffer. [default: -1]

Events

readable	Issued when there is new read data available.
writable	Issued when the stream becomes empty. `.

Returns: A count of the bytes actually read. Returns null on EOF or errors.

write(data: Array): Number

Description: Write data to the stream. If the stream can accept all the write data, the call returns immediately with the number of bytes written. If writing more data than the stream can absorb in sync mode, the call will block until the data is written. If writing more data than the stream can absorb in async mode, the call will not block and will buffer the data and return immediately. Some streams will require a flush() call to actually send the data. A "writable" event will be issued when the stream can again absorb more data.

Parameters

data: Array

Data to write.

Events

readable	Issued when data is written and a consumer can read without blocking.
writable	Issued when the stream becomes empty and it is ready to be written to.

Returns: A count of the bytes actually written.

Throws: IOError: if there is an I/O error.