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 address 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. The detailed state additionally tells you how this condition came to be.
For example, the "simplified" PL_SSTS_CLOSED state means that the connection is closed (socket is idle). It doesn't tell you, however, why it is closed. The "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 the event queue can contain multiple such events. A separate event is generated for each new state the socket enters.
The newstate and newstatesimple arguments were 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. Suppose that when a 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:
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
if ser.enabled= YES then 'connection is NOT established? Close and clear the port if it is opened!
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 the 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. Suppose that you want to "play" an LED pattern that depends on the current state of the socket. Here is how you do this:
'this event is generated each time a pattern finishes playing
select case sock.statesimple
case PL_SSTS_EST: 'connection is established- Green LED on
case PL_SSTS_ARP: 'ARP in progress- Green LED blinks
case PL_SSTS_PO: 'connection is being established- green LED goes 'blink-blink-blink'
case PL_SSTS_AO: 'connection is being established- green LED goes 'blink-blink-blink'
case else: 'connection is closed or being closed- green LED is 'blink-blink'
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 if it was a broadcast — the sock.bcast read-only property 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.
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 receives. If you check 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 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!