Processing Inband Commands

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. Suppose that you have the following setup:

Tibbo BASIC

							...
							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 effects:

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

Note 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 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 sock.getdata, minus the maxinplen argument. The total amount of data in the CMD buffer can be checked through the sock.cmdlen read-only 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:

Tibbo BASIC

							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
						

A warning note icon. For the above example to work well, the size of the CMD buffer must not exceed the capacity of the string variable s. This way whatever is extracted from the CMD buffer will always fit in s. 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 Commands

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.