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): 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): 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): 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): Disconnects a group of clients. The value of group has the same meaning as for broadcast(). groupsOf(client): Returns an array with all the groups the specified client is a member of. joinGroup(client, group): 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): 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): 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): 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.