Protocol Functions
All protocol function calls pass a single parameter – the protocol table.
This protocol table is an object that you can call all the source function methods on.
Additionally, it contains all of the parameters (as defined by the user), and a field “.n” that specifies the channel number.
Sometimes the protocol requires a particular action when setup.
This call is made when a channel starts firing up the protocol.
function protocols.myprotocol.setup(p)
-- do something
--return true --reload the configuration
return false --just continue
end
It is illegal to attempt to read or write to the source – it is not connected yet.
However, you can choose to initialise variables that are required by the protocol.
Additionally the protocol's setup function can make changes to the source parameters before continuing.
For example, a protocol may choose to force the TCP port number for the channel:
protocols.myprotocol.setup(p)
if c.chnl[p.n].src.tcp.port ~= 23
then
c.chnl[p.n].src.tcp.port = 23
return true
end
return false
end
The function will check the port number and force it to 23 if different. Note that the change will be stored and will effectively overwrite the user's input.
Like the .setup function, the connect function can be used to setup various working variables for the protocol (like timeout values and clearing buffers).
It is called whenever the source enters the “connected” state.
COM and UDP sources will “connect” immediately. A TCP source will call this when the socket connects and the match/send have completed. An FTP Server source will call this when the FTP client logs in with the username/password that match the source channel.
Unlike the .setup function hook you can read and write to the source.
function protocols.myprotocol.connect(p)
p:write('Hello') --send a string
p:readline(1000) --wait 1second for a response
end
Additionally, the protocol can choose to close the source and issue an error:
function protocols.myprotocol.connect(p)
p:write('Hello') --send a string
s,t = p:readline(1000) --wait 1second for a response
if t
then
p:error('No response')
p:close()
end
p:write('Now we are running')
end
This functionality is required for the Avaya RSP, for example, where on connection there is an initial conversation to establish the link.
Many protocols require timeouts to be kept, and other actions.
The Lua protocol framework allows for a function hook that is called every second, while there is no incoming data.
You can perform any action within the second event hook.
function protocols.ascii.second(p)
if (p.xontime>=30)
then
if (p.xon == 1) then p:writebytes(0x11) end
p.xontime=0
end
p.xontime=(p.xontime or 0) + 1
end
The above function is from the supplied “ASCII lines” protocol. It keeps track of the idle count with the p.xontime counter.
When that exceeds 30, the protocol will send an XON character – only if the user has configured it and the p.xon variable is therefore 1.
Some protocols may perform keep-alive checks with the other end, and decide to close the connection if there is a serious timeout (as is the case with the Avaya RSP protocol).
Whenever data arrives at the source, the Lua protocol framework will make a call to the .data function hook of the protocol. It is the responsibility of this function to read data from the source, respond if necessary, and store any data that is considered valid.
As a very simple example:
function protocols.ascii.data(p)
local s=p:readline()
p:store(s,"ascii")
end
This function simply calls the source.readline function, pulling the data into a local variable s.
That string is then stored with the tag “ascii” - which involves the optional
time stamping.
local keyword: it is vitally important that you use the local keyword when defining variables that are used within the scope of a single function.
If you do not, then the variables will be global and can be read, modified, and corrupted by other channels that are using the same protocol or variable name.
Some protocols will require assembling a “frame” of data and perhaps isolating the data.
The NEC NEAX2400 serial protocol is an example that is worth analysing:
function protocols.nec.data(p)
local r,s
p._buff = (p._buff or "")..p:read()
p.time=0
if string.len(p._buff)>2048 then p._buff=string.sub(p._buff,-
2048,-1) end
while true
do
_,r,s=string.find(p._buff,"\002(.-)\003")
if not (s) then break end
if (s) then p:store(s.."\r\n","cdr nec") end
p._buff=string.sub(p._buff,r+1,-1)
end
end
This code builds a buffer that is local to the protocol (stored in p._buff).
Any variables that begin with an underscore will not appear in the diagnostic dump output.
The buffer length is then limited to 2k. Finally, in a “while true” loop the Lua script searches for pattern captures between the 0x02 and 0x03 characters.
Any matching captures are stored in the “s” local variable and are then stored with a CR/LF suffix to the flash.
(There is some other code that uses the .second function to clear the buffer – just in case the protocol is selected and we are being sent non-NEC data!)
#Firmware/v320
To correspond with the protocol's .connect function, .disconnect is called when closing down - just after x.chnl[#].src.onclosing is called (see x.chnl.src - Source Hooks).
function protocols.mine.disconnect(p)
-- Do other stuff
log.write('mine', 'disconnecting')
end