TcpSocketServer
The TcpServer object allows Q-SYS cores to accept client TCP/IP connections from devices on the network. The TcpSocketServer is different from the TcpSocket library because of the inbound/waiting nature of a TCP Server. TcpSocket generally allows Q-SYS to establish outgoing TCP client sessions to remote TCP Servers. The TcpSocketServer library enables a script to create a TCP "listener" on a specific TCP port. This listener isn't the individual TCP socket itself–it "emits" a unique TcpSocket instance whenever a remote TCP client connects to the listen port. Thus, the TcpSocketServer instance's EventHandler is where the specific incoming TCP socket connection is granted a unique socket instance(the argument of the TcpSocketServer's EventHandler function). The EventHandler target function for this new socket instance will be defined as an anonymous function or (more likely) as a reference to a separate socket event handling function. It is important to note that if multiple incoming socket connections are made, a separate socket instance (and EventHandler) are created by the Lua runtime engine for each connection and all socket transactions are handled by each socket connection's separate EventHandler instances (which are assigned only as necessary).
|
TcpSocketServer Properties |
||
|---|---|---|
|
Name |
Arguments |
Description |
| .EventHandler |
Signature of function is 'function(socket) |
Function called on any incoming socket event. See definition of 'event' in the table below. |
|
TcpSocketServer Methods |
||
|---|---|---|
|
Name |
Arguments |
Description |
|
none |
Creates a new TcpServer instance |
|
|
( port ) |
Attempts to connect to specified port |
|
|
( none ) |
Disconnects the socket |
|
New()
Purpose: Static class method. Creates a new instance of the TcpServer class.
Response: server
Type: TcpServer
Definition: The newly created server
Listen( )
Purpose: Opens the TcpServer on specified TCP port on all network interfaces
Parameter: port
Type: integer
Definition: The port to use for listening for connections
Response: error
Type: string
Definition: nil if open succeeded, otherwise a string representing the error
Close()
Purpose: Closes the TcpServer
Example
Note that in the following example, the EventHandler arguments and function names were chosen to assist in understanding what is happening when a TCP socket connection occurs. These names are not special and can be changed in your own scripts. But simply calling everything 'sock' throughout can be confusing when learning the concept.
|
server = TcpSocketServer.New()
function SocketHandler(NewSocketInstance, event) -- the arguments for this EventHandler are documented in the EventHandler definition of TcpSocket Properties print( "TCP Socket Event: "..event ) if event == TcpSocket.Events.Data then print( NewSocketInstance, NewSocketInstance:Read(NewSocketInstance.BufferLength) ) end end
server.EventHandler = function(SocketInstance) -- the properties of this socket instance are those of the TcpSocket library SocketInstance.ReadTimeout = 10 print( "Got connect", SocketInstance ) SocketInstance.EventHandler = SocketHandler end
server:Listen(1720) -- This listen port is opened on all network interfaces |
