Processing Inband Commands

Top  Previous  Next

What goes into the CMD buffer

All incoming inband commands are stored into the CMD buffer. At any given time the buffer may contain more than one command. Each inband message in the buffer already has its escape character and the character after the escape character removed. The end character, however, is not removed and can be used by your program to separate inband messages from each other.

Here is an example. Supposing, you have the following setup:

 

 

...

sock.inbandcommands= YES

sock.escchar=`@`

sock.endchar=`&`

...

 

 

Here is a sample data stream:

 

Data@command1&Moredata@!command2&Evenmoredata

 

This incoming data stream will have the following effect:

The RX buffer will receive this data: "DataMoredataEvenmoredata".
The CMD buffer will receive: "ommand1&command2&"

 

Notice, that the first inband command is missing the first character- this is because when the inband command is being processed both its escape character and the character following the escape character are removed. End characters of both inband commands are preserved so you can tell where each one ends.

Extracting the data from the CMD buffer

Extracting data from the CMD buffer is similar to extracting data from the RX buffer. A dedicated method- sock.getinband- does the job. This method is just like the sock.getdata, minus the maxinplen argument. Total amount of data in the CMD buffer can be checked through the sock.cmdlen property.

Once extracted, the data is no longer in the buffer. You can use the sock.cmdlen property to check how much data is waiting in the CMD buffer. There is no dedicated property to tell you the buffer capacity- just remember what the sock.cmdbuffrq method returned if you have to know this!

The on_sock_inband event is generated whenever there is some data in the CMD buffer, but only once. There are never two on_sock_inband events waiting in the queue. The next event is only generated after the previous one has completed processing, if and when there is any data available in the CMD buffer.

Inband commands only appear in the CMD buffer in their entirety. That is, if the buffer was previously empty and you get the on_sock_inband event then you are guaranteed that the buffer will contain a full command (or several full commands).

Here is an example:

 

 

sub on_sock_inband

 dim s as string 'we will keep the data from the CMD buffer here

 dim s2 as string 'this will keep individual inband commands

 dim x as byte

 

 s=sock.getinband 'we get entire CMD buffer contents into the s

 x=instr(1,s,chr(sock.endchar))

 while x<>0

         s2=left(s,x-1) 's2 now contains a single inband command

         s=right(s,len(s)-x) 'cut out this command

         

         'process inband command in the s2 as needed

         ...

         ...

         

         'any more inband commands to process now?                

         x=instr(1,s,chr(sock.endchar))

 wend

end sub

 

 

note_warning-wt

For the above example to work well, the size of the CMD buffer must not exceed the capacity of string variable s. This way whatever is extracted from the CMD buffer will always fit in s. A slightly more complex processing is needed if the buffer is larger than the capacity of s.

Are CMD buffer overruns possible?

CMD buffer overruns are not possible. If the socket receives an inband command that cannot be saved into the CMD buffer in its entirety, then the socket will discard the whole command (your program won't be notified of this in any way). Therefore, you are guaranteed to always receive complete inband commands, or nothing at all.

Incomplete inband commads

Take a look at this datastream:

 

Data@!comma@!command2&Moredata

 

What we have here is an inband command that is incomplete- a new inband command starts before the previous one ends. Such incomplete commands are discarded and not recorded into the CMD buffer.