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 on_sock_event "brings" two arguments with it — newstate and newstatesimple. These arguments contains the state of the socket at the moment when the on_sock_event was generated.

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:

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

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

There is an intricate detail to understand about the sock.remotemac, sock.remoteip, sock.remoteport, and sock.bcast properties when you are using UDP.

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!

Checking the 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.