Sockets/A

Proposal A, Draft 1 (in development)

The "socket" module supports the Socket API, providing an interface for socket manipulation.

For the purpose of this documentation, "soc" is a variable name for any object that implements the Socket API, including the exports of the "socket" module

Interface

var s = new Socket(family, type)

The Socket class is used to create a non-blocking TCP socket.

• family = AF_INET (default), AF_INET6 or AF_UNIX.
• type = SOCK_STREAM for TCP (default) or SOCK_DGRAM for UDP). Others (RAW, RDM, SEQPACKET)?

Sockets

The "socket" module must export the following:

connect( host, port [, timeout] )

Initiate a connection on a socket. Connect to a remote port on the specified host with a connection timeout. Throws an exception in case of failure.

• host: IP address or hostname
• port: port number or service name
• timeout: timeout value (default X microseconds)

accept()

Accept a connection on a socket. Returns a new (connected) Socket.

bind( [host] [,port])

When a new socket is created, it has no address bound to it. Bind assigns the specified address (also known as name) to the socket. Throws an exception in case of failure.

• host: address (interface) to which the socket will be bound. If address is ommited, any address is will match.
• port: port number or service name to which socket is to be bound. If port is undefined, the socket wont bind to any port.

listen()

Listen for incoming connections on a socket (use before an accept). Throws an exception in case of failure.

shutdown([what])

Shut down part of a full-duplex connection on a socket. If [what] is SHUT_RD, further receives will be disallowed. If [what] is SHUT_WR further sends will be disallowed. If what is SHUT_RDWR, further sends and receives will be disallowed.

• what: SHUT_RD, SHUT_WR or SHUT_RDWR

close()

Close the socket immediately

receive/read( [maxlen])

Receive a block of bytes from the socket. Returns block of bytes read

• maxlen: number of bytes to read. Default: X bytes

send/write(data)

Send a block of bytes to the socket

• data: block of bytes to send

receiveFrom( [maxlen])

Receive all data from socket. Returns object with ip_address and port of sender along with data properties

• maxlen: number of bytes to read. Default: X bytes

sendTo( host, port, data)

Send a block of data to a specific host and port

• host: IP address or hostname
• port: port number or service name
• data: block of bytes to send

sendFile(file)

Sends a complete File object across a socket.

• file: a File object

setOption( option, value)

Set socket option value to socket option name

getOption()

Get socket option value, option should be socket option name

Tests

isConnected

Returns TRUE if the socket is in a connected state - READ ONLY

isWritable

Returns TRUE if socket can accept written data - READ ONLY

isReadable

Returns TRUE if data is waiting to be read from socket - READ ONLY

Metadata

localAddress

Get local socket IP address. Returns the IP address for this socket.

localPort

Get local socket port number. Returns the port number for this socket.

remoteAddress

Get remote socket IP address. Returns the IP address for this socket.

remotePort

Get remote socket port number. Returns the port number for this socket.

type

Socket type, SOCK_STREAM (TCP) or SOCK_DGRAM (UDP)