Checking Connection Status
Simplified and detailed socket states
The sock object features several properties that provide complete information on what the socket is doing, which IP and port it is engaged in the connection with, etc.
The most important of all this data is the socket state. Two state groups are supported- "simplified" and "detailed". Simplified state tells you, generally, what condition the socket is in. Detailed state additionally tells you how this condition came to be.
For example, the "simplified" PL_SSTS_CLOSED state means that connection is closed (socket is idle). It doesn't tell you, however, why it is closed. "Detailed" state PL_SST_CL_ARESET_CMD tells you that connection is closed because there was an active close as a result of the sock.close method invocation from your program!
On_sock_event and sock.event, sock.eventsimple read-only properties
Each time the socket state changes an on_sock_event event is generated. Unlike many other events, this one can be generated again and again before the on_sock_event handler is invoked, so event queue can contain multiple such events. A separate event is generated for each new state the socket enters.
The on_sock_event "brings" two arguments with it — one is called "newstate", another one — "newstatesimple". These arguments contains the state of the socket at the moment when the on_sock_event was generated.
Newstate and newstatesimple arguments have been introduced in Tibbo BASIC/C V2.0. Before, their role was played by two read-only properties — sock.event and sock.eventsimple. These properties are no longer available.
Here is one example of how on_sock_event can be used. Supposing, when connection is established we need to open the serial port and when it is no longer established close the serial port and clear the data from its TX and RX buffers:
** Tibbo Basic **
sub on_sock_event(newstate as pl_sock_state,newstatesimple as pl_sock_state_simple) if newstatesimple= PL_SSTS_EST then ser.enabled= YES 'connection has been established- open port else if ser.enabled= YES then 'connection is NOT established? Close and clear the port if it is opened! ser.enabled= N0 ser.txclear ser.rxclear end if end if end sub
Sock.state and sock.statesimple read-only properties
There is also a pair of read-only properties- sock.state and sock.statesimple- that allows you to check current socket state (as opposed to the state that was at the moment of on_sock_event generation).
Here is an example of how you can use this. Supposing, you want to "play" an LED pattern that depends on the current state of the socket. Here is how you do this:
** Tibbo Basic **
sub on_pat 'this event is generated each time a pattern finishes playing select case sock.statesimple case PL_SSTS_EST: 'connection is established- Green LED on pat.set("GGGGGGGGGGGGGGGG",NO) case PL_SSTS_ARP: 'ARP in progress- Green LED blinks pat.set("G-G-G-G-G-G-G-G-",NO) case PL_SSTS_PO: 'connection is being established- green LED goes 'blink-blink-blink' pat.set("----------G-G-G-",NO) case PL_SSTS_AO: 'connection is being established- green LED goes 'blink-blink-blink' pat.set("----------G-G-G-",NO) case else: 'connection is closed or being closed- green LED is 'blink-blink' pat.set("------------G-G-",NO) end select end sub
Understanding who you are talking to
Whenever the socket is engaged in the connection you can check the parameters of the other side through three read-only properties- sock.remotemac, sock.remoteip, and sock.remoteport. For UDP, you can also check if the datagram you have received was sent to your device exclusively or it was a broadcast- the sock.bcast will tell you that. For TCP, you can additionally check if the socket is in the "regular data" or HTTP mode- just check the sock.httpmode property.
There is an intricate detail to understand about the sock.remotemac, sock.remoteip, sock.remoteport, and sock.bcast properties when you are using the UDP protocol.
With UDP, your socket may be accepting datagrams from several different hosts. As will be explained in Receiving Data in UDP Mode, the most common way to handle the incoming data is through the on_sock_data_arrival event. You will get one such event for each UDP datagram that the socket will receive. If you check the sock.remotemac, sock.remoteip, sock.remoteport, or sock.bcast from within the on_sock_data_arrival event handler you will get the sender's data for the UDP datagram currently being processed.
On the contrary, using sock.remotemac, sock.remoteip, sock.remoteport, or sock.bcast property outside of the on_sock_data_arrival event handler will give you the data for the most recent UDP datagram received into the RX buffer of the socket. This is not the same as the next UDP datagram to be extracted from the RX buffer and processed by your application!
Checking current interface
Starting from V1.2, the sock object provides an additional property, sock.currentinterface, which tells you which network interface the network connection is going through.