SockIt · API

Download

Home · Quick Tutorial · Full Tutorial · Demos · API · Source Documentation · Developers

Top Level API

createThread()

Creates a new thread on which to create new clients and servers.

returns A new thread, on which we can create new clients and servers.

toBinary(data)

Converts an array of bytes by encoding each byte into a UTF-16 character, and returns a UTF-16 string encoded from the given data.

`data`	An array of 1-byte integers, which will be converted into a string.
`returns`	A UTF-16 string encoded from the given data.

fromBinary(data)

Converts a UTF-16 string into an array of bytes.

`data`	The UTF-16 string to convert to bytes.
`returns`	An array of bytes, the result of decoding `data` character by character.

createTcpServer(port [, options])

Creates a TCP server, but does not start the server listening.

port An integer representing the port on which the server will listen.

options An optional map of strings to strings, which enumerates further options for the TCP connections for this server, and controls the underlying TCP sockets. If this map is not provided, each property takes its default value.

`doNotRoute`	Specifies whether this server should disable routing on its TCP connections. If this field is set to `false` or is not provided, the server defaults to `false`, so that routing is enabled.
`ipv6`	Specifies whether this server should use IPv6 over IPv4. If this field is set to `false` or is not provided, the server defaults to IPv4.
`keepAlive`	If this field is set to true, then the underlying TCP connection will try to maintain a keep-alive connections with clients. By default, this field is `true`.
`keepAliveTimeout`	If this field is set, then the underlying TCP connection will maintain a keep-alive connections with this specified timeout, interpreted in milliseconds.
`noDelay`	Setting this field to `true` forces the underlying TCP connections to disable Nagle's algorithm for TCP. By default, this field is `false`.

returns A newly created TCP server, which is not yet listening.

createUdpServer(port [, options])

Creates a UDP server, but does not start the server listening.

port An integer representing the port on which the server will listen.

options An optional map of strings to strings, which enumerates further options for the UDP connections for this server, and controls the underlying UDP sockets. If this map is not provided, each property takes its default value.

`ipv6`	Specifies whether this server should use IPv6 over IPv4. If this field is set to `false` or is not provided, the server defaults to IPv4.
`doNotRoute`	Specifies whether this server should disable routing on its UDP connections. If this field is set to `false` or is not provided, the server defaults to `false`, so that routing is enabled.
`multicast`	Specifies whether this server should enable UDP multicast. If this field is not provided, it defaults to `false`, such that multicast is disabled for this server. If this is set to true, `MulticastGroup` must also be specified, and `ReuseAddress` will be set to true.
`multicastGroup`	The multicast group to which this UDP server has subscribed and from which it will receive messages. This field has no default value.
`multicastTTL`	The multicast TTL for this UDP server, or the number of router hops that a multicast message sent from this server will make. This field has no specified default value. Note that large values may be ignored by routers.
`reuseAddress`	Specifies whether this server should fail if the port on which it should listen already has another socket bound to it. By default, this parameter is `false`, so that the server will not try to reuse addresses and will fail if another socket is already bound to the port. This is automatically set to `true` if `Multicast` is enabled.

returns A newly created UDP server, which is not yet listening.

createTcpClient(hostname, port [, options])

Creates a TCP client.

hostname A string, the hostname or IP address to which this client should connect.

port An integer representing the port to which the client will connect.

options An optional map of strings to strings, which enumerates further options for the TCP connections for this client, and controls the underlying TCP socket. If this map is not provided, each property takes its default value.

`doNotRoute`	Specifies whether this client should disable routing on its TCP connections. If this field is set to `false` or is not provided, the client defaults to `false`, so that routing is enabled.
`ipv6`	Specifies whether this client should use IPv6 over IPv4. If this field is set to `false` or is not provided, the client defaults to IPv4.
`keepAlive`	If this field is set to true, then the underlying TCP connection will try to maintain a keep-alive connections with servers. By default, this field is `false`.
`keepAliveTimeout`	If this field is set, then the underlying TCP connection will maintain a keep-alive connections with this specified timeout, interpreted in milliseconds.
`noDelay`	Setting this field to `true` forces the underlying TCP connections to disable Nagle's algorithm for TCP. By default, this field is `false`.

returns A newly created TCP client.

createUdpClient(hostname, port [, options])

Creates a UDP client.

hostname A string, the hostname or IP address to which this client should connect.

port An integer representing the port to which the client will connect.

options An optional map of strings to strings, which enumerates further options for the UDP connections for this client, and controls the underlying UDP sockets. If this map is not provided, each property takes its default value.

`doNotRoute`	Specifies whether this client should disable routing on its UDP connections. If this field is set to `false` or is not provided, the client defaults to `false`, so that routing is enabled.
`ipv6`	Specifies whether this client should use IPv6 over IPv4. If this field is set to `false` or is not provided, the client defaults to IPv4.
`multicast`	Specifies whether this client should enable UDP multicast. If this field is not provided, it defaults to `false`, such that multicast is disabled for this client. If this is set to true, `MulticastGroup` must also be specified, and `ReuseAddress` will be set to true.
`multicastTTL`	The multicast TTL for this UDP client, or the number of router hops that a multicast message sent from this client will make. This field has no specified default value. Note that large values may be ignored by routers.

returns A newly created UDP client.

Thread API

Mirrors the top level API, except that it does not contain the createThread method.

Client API

The API exposed to both UDP and TCP clients contain these common functions.

send(data)

Asynchronously sends some data to the remote endpoint for this client.

data A string, the data the client should be sent to the remote endpoint.

sendBytes(data)

Asynchronously sends some bytes of data across the connection.

data An array of bytes to send over the connection.

close()

Gracefully shuts down the client, freeing all resources once pending sends have been completed.

getHost()

Gets the hostname to which this client connects.

getPort()

Gets the port on which this client will connect to the remote host.

Server API

The API exposed to both UDP and TCP servers contain these common functions.

listen()	Starts up the server listening on the port given.
close()	Gracefully shuts down the server, freeing the port and resources once any pending sends have completed. The server will continue to listen for connections and incoming data until all pending sends have been sent.
getPort()	Returns the port on which this server listens.

Event API

The API exposed to the event parameter of the data handler function, which allows reading and sending data.

send(data)

Asynchronously send back some data across the connection.

data A string, the data the client should be sent to the remote endpoint.

sendBytes(data)

Asynchronously send back some byte data across the connection.

data An array of bytes, which will be sent to the remote endpoint as binary data.

read()

Read the string data that triggered this event.

returns A string, the data received that triggered this event.

readBytes(data)

Read the bytes of the data received that triggered this event.

returns An array of bytes, representing the data received that triggered this event.

getHost()

Returns the hostname from which the data was received.

getPort()

Returns the port from which the data was received on the remote host.

Events

The events for which we can attach Javascript event handlers to perform callbacks.

data	This event can occur on server or clients, and is fired whenever a connection receives some data.
error	This event can occur on clients or server objects, and is fired whenever an unrecoverable error occurs.
close	This event occurs whenever a client or server completely shuts down, after the `close` function
open	This event occurs once a server successfully opens a new socket and begins listening for incoming connnections
resolve	This event occurs once a client successfully resolves the hostname of its remote endpoint
disconnect	This event occurs for TCP clients and servers when an error occurs that severs the TCP connection.

Home · Quick Tutorial · Full Tutorial · Demos · API · Source Documentation · Developers