Sockets/A

From CommonJS Spec Wiki
Jump to: navigation, search

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)