Properties:
running: read-only boolean indicating if the server is running or not
packetLimit: maximum amount of bytes a client can send in a single packet
before overflowing (0 = no limit)
clients: read-only array with all the client IDs. This will fail if
the client is not running
groups: read-only array with all the group IDs. This will fail if
the client is not running
newGroupID: read-only integer having an unused group ID. This will fail
if the client is not running
openCallback: callback to be invoked when a new connection arrives. The
callback receives as arguments the new client's ID and the
server object itself
closeCallback: callback to be invoked when a client closes its connection.
The callback receives as arguments the closed client's old
ID (now become invalid) and the server object itself
receiveCallback: callback to be invoked when a packet arrives from a client.
The callback receives as arguments the received packet (as
a string), the sender client's ID and the server object
overflowCallback: callback to be invoked when a connection overflows the
maximum packet size (as imposed by packetLimit). When this
occurs, any further data received from that client should
not be relied upon (therefore, closing the connection here
is recommended). The callback receives the client's ID and
the server object as arguments.
Any of the first three callback properties can be set to false, in which case
no callback is invoked. If overflowCallback is set to false, a default callback
which closes the connection and invokes closeCallback is used.
splitMode, delimiter: these two properties work together, and specify how the
data received by the client should be split into packets.
Legal values for splitMode (and their semantics, together
with the meanings for delimiter they specify) are these:
Value Semantics
--------------------------------- ---------------------------------------------
SERVER_SPLIT_PACKET No splitting is performed, packets are sent
to the reception callback as received. This
is useful if the implementor wants to handle
the splitting instead of letting the server
do so. The value of delimiter is meaningless.
It should be noted that packetLimit is also
used as the maximum packet size to receive at
once -- if there's no limit, a default of two
kilobytes is used.
--------------------------------- ---------------------------------------------
SERVER_SPLIT_CHAR Packets are split when a certain character is
encountered. The value of delimiter specifies
the character, and it should be either the
value of the character (from 0 to 255) or a
string of length one containing it. The
character in question is discarded and not
sent to the reception callback.
--------------------------------- ---------------------------------------------
SERVER_SPLIT_NEWLINES Packets are split at newline boundaries (that
SERVER_SPLIT_NEWLINES_NO_BLANKS is, at CR, LF or CRLF). The delimiter value
is meaningless. The newline separator is
discarded. The _NO_BLANKS version also makes
lines of length zero to be discarded.
It should be noted that the default split
mode is SERVER_SPLIT_NEWLINES_NO_BLANKS.
--------------------------------- ---------------------------------------------
SERVER_SPLIT_LENGTH Packets are split at fixed length boundaries.
The value of delimiter specifies how many
bytes a packet will have, and it should be a
positive integer.
--------------------------------- ---------------------------------------------
SERVER_SPLIT_BYTES_AFTER_BYTE Packets are split at a certain amount of
SERVER_SPLIT_BYTES_AFTER_16LE bytes specified by a value in the packet
SERVER_SPLIT_BYTES_AFTER_16BE itself. The delimiter property indicates how
SERVER_SPLIT_BYTES_AFTER_32LE many bytes offset from the beginning will
SERVER_SPLIT_BYTES_AFTER_32BE this value be, and it should be a positive
integer or zero. The size of the value itself
and its endianness are specified by the value
of splitMode (one of the five constants).
That value indicates how many more bytes
after it will the packet have, at which point
the packet is split.
--------------------------------- ---------------------------------------------
Methods:
open(port):
Opens the server, listening on all available IPs at the specified port. (The
server uses TCP/IPv4 connections.) This method will not return while the
server is running, although it will call the callbacks when needed. This
method returns 0 if the server is closed manually (calling the close() method),
or a negative error constant if something fails:
SERVER_ERROR_INVALID_PORT: the specified port is not a valid port
(ports are positive integers no larger
than 65535)
SERVER_ERROR_CANNOT_CREATE_SOCKET: creating the listening socket failed.
This might happen if the specified port
is busy, or if you don't have the needed
privileges to listen at that port
SERVER_ERROR_CANNOT_READ: an error occurred while attempting to
receive data from active connections
SERVER_ERROR_LISTENING_SOCKET_KILLED: the listening socket that the server
uses to run was closed by an agent
external to the server
SERVER_ERROR_ALREADY_RUNNING: open() was called when the server was
running. Call close() before reopening
close():
Closes the server. This will close all outstanding client connections, flush
all buffers, delete all groups and call no callbacks.
send(client, data, mode = SERVER_SEND_ALL):
<can only be called when the server is running>
Sends the specified data to the specified client. If client is an array, it
sends that data to all clients. Data can be an integer (in which case it is
truncated to 8 bits and sent as a single byte); an array of byte-wide (i.e.,
integers from 0 to 255) values, which are sent as a single buffer; or a string,
which is sent according to the sending mode. The sending mode is one of the
following values:
SERVER_SEND_ALL: the buffer is sent as-is, without any modifications
any positive integer: a buffer as big as the value specifies is sent. If the
string is larger, it is truncated; if it is smaller, it
is padded with nulls
SERVER_SEND_LINE: sends only the first line (up to a CR, LF or CRLF),
including its terminator
SERVER_SEND_LINE_NO_NEWLINE: same as SERVER_SEND_LINE dropping the terminator
SERVER_SEND_LINE_CR, SERVER_SEND_LINE_LF, SERVER_SEND_LINE_CRLF: same as
SERVER_SEND_LINE_NO_NEWLINE but adding the specified
terminator
broadcast(data, group = 0, mode = SERVER_SEND_ALL):
<can only be called when the server is running>
Sends the specified data to the specified group of recipients. A value of 0
for group indicates all connected clients; a negative value, all clients but
the one specified by the absolute value of that number; and a positive one, all
clients added to a certain group. The value of mode is the same as for send()
disconnect(client):
<can only be called when the server is running>
Disconnects a client. Also causes its buffer to be flushed with no callbacks
being called in the process. If client is an array, all specified clients are
disconnected.
disconnectMultiple(group = 0):
<can only be called when the server is running>
Disconnects a group of clients. The value of group has the same meaning as for
broadcast().
groupsOf(client):
<can only be called when the server is running>
Returns an array with all the groups the specified client is a member of.
joinGroup(client, group):
<can only be called when the server is running>
Makes a client join a group. If the group doesn't exist yet, it is created.
Both arguments can be arrays, in which case the method is called for every
element of the array. (If both are arrays simultaneously, it is called for
every pair.)
leaveGroup(client, group):
<can only be called when the server is running>
Makes a client leave a group. If it's the last client in that group, the group
is deleted. Like for joinGroup(), both arguments can be arrays.
deleteGroup(group):
<can only be called when the server is running>
Deletes a group, making all clients in it leave it. The argument can be an
array, in which case all specified groups are deleted.
clientCallback(client):
<can only be called when the server is running>
clientCallback(client, callback):
Returns or sets a callback for receiving data on a client. Any events that
occur on this client (other than an overflow) cause the client's callback to be
called instead of the normal callback. (Setting it to false reverts to the
default behavior.) The callback receives the packet (null if the event is a
connection close), the server object itself, and the client's ID.
Comments