In XTension version 9.3.3 the API version was updated to version 2 and support for listening or incoming connections was added. This is currently incomplete documentation as that version hasn’t been released yet. Stay tuned for more info.
The XTStartTCPListener command will startup a listening server on the requested port for the requested protocol. The function will return an ID number if the startup was successful or 0 if the port was in use or other error occurred. You should save the returned ID in order to stop the server listening later. The same automatic boundary parsing that can be applied to interface started connections can be applied to this. The connection events and data available events are described below in the Server Events section.
myServer = XTStartTCPListener( thePort, theBoundryString) if myServer == 0: XTWriteLog( “an error occurred trying to bind a new listener to port “ + str( thePort))
Pass the server id returned from the XTStartTCPListener command.
The XTStartUDPListener is used for receiving UDP datagrams. Only the port parameter is needed to startup the listener. Datagrams will be passed to the XTReceivedDatagram event. The only needed parameter is the port. The function will return an ID number if the open is successful and a 0 if there was an error. You should save the server id as you will need it to send datagrams, join or leave multicast groups and shutdown the server.
myServer = XTStartUDPListener( thePort) if myServer == 0: XTWriteLog( “an error occurred trying to bind a new listener to port “ + str( thePort))
Pass the ID number you received from the XTStartUDPListener command.
Pass the ID number you received from the XTStartUPListener command and the name/address of the multicast group. Returns a boolean true if the join was successful.
if not XTJoinMulticastGroup( myServer, multicastAddress): XTWriteLog( “there was an error joining the multicast group”)
Pass the ID number you received from the XTStartUDPListener command and the name/address of the multicast group.
XTLeaveMulticastGroup( myServer, multicastAddress)
Used to send a datagram through a UDP socket. Required parameters are the id of the server returned from the XTStartUDPListener or from the id passed in a received datagram event, the address you wish to send the packet to, the port you wish to send the packet to and finally the actual data you wish to send. In order to send a broadcast packet pass the xtBroadcastAddress constant instead of a specific IP address in the remoteAddress field.
XTSendDatagram( myServer, remoteAddress, remotePort, theData)
The XTStartHTMLListener command can be used to startup an HTTP capable server. You will receive page request events along with all the data about the requester and any form data or post data, You can then send a response code and data. Page returns must be made inline as the connection is not kept open after the event returns.
The XTNewConnection event is called when a remote device is attempting to connect to the port you’re listening on. The function will receive 2 parameters, the first is a string and is the unique ID of the specific socket stream. This ID will be passed to you with every data packet reception and must be specified by you whenever you’re writing to an outgoing socket so that XTension knows which open pipe to send the data down. The second parameter is a python dictionary that contains as much data as is known about the connection and the remote host. Implementing this event is required to support incoming connections.
def XTNewConnection( theConnectionID, theConnectionInfo): XTWriteLog( “A new connection was received from address: “ + theConnectionInfo[ xtKeyRemoteAddress]) return true # return true to accept the connection or false to force it closed immediately.
The following keys into the dictionary are available for every connection:
The data available call is similar to the XTDataAvailable event for a standard outgoing connection. The difference is that when made from a listening or script defined outgoing socket there will be 3 parameters as the connection ID and connection info dictionary will also be passed along with the received data. If you have started the server with a parsing boundary setting then these events will be called pre-parsed one event for each packet received. If not then it will be up to you to manage a buffer as there is no guarantee from TCP that each event will contain one packet, there may be partial packets or several together in one event. This handler is required for a script defined socket or listening interface.
def XTDataAvailable( theData, theConnectionID, theConnectionInfo):
If the connection throws an error the XTSocketError function will be called. This will pass 2 parameters the same as the XTNewConnection function but in this case the connection info dictionary will also contain 2 more keys for the error number and the error description if any. Note that this may also be called for normal disconnection of a connection with the appropriate error code. Use the other info in the info dictionary and or uniqueID to remove any saved references you have for the stream. After the processing of your error handler the socket will be closed and removed from the array of active connections. It is not necessary to also call the disconnect method.
def XTSocketError( theConnectionID, theConnectionInfo): if theConnectionInfo[ xtKeyErrorNumber] == 102: XTWriteLog( “the connection from Mac Address: “ + theConnectionInfo[ xtKeyMacAddress] + “ has been closed”) else: XTWriteLog( “error “ + str( theConnectionInfo[ xtKeyErrorNumber]) + “ “ + theConnectionInfo[ xtKeyErrorMessage] + “ has occurred.”)
For the entire list of constants in these objects please see the XTensionHelpers.py file in the example plugin:
Download sample plugin 6 Channel PWM Dimmer Kit Driver