Tasks

True to the non-blocking operation philosophy of TiOS, the wln. object does not stall the entire Tibbo BASIC/C application execution to wait for the Wi-Fi interface to complete an operation ("task"). Your program gives the wln. object a task to perform, and then it is free to go and do other things. The only exceptions are the wln.boot and wln.waitforupgradecompletion methods. They stall your system until they are done executing.

There are nine Wi-Fi activities that are implemented as tasks:

The wln. object can only handle one task at a time. Before executing the next task method, your app must make sure that the previous task has completed. You can find this out through the wln.task read-only property. Three tasks on the list — wln.setwep, wln.setwpa, and wln.settxpower — are so-called immediate tasks. They complete as soon as they are started. If the execution advances to the next statement in the program, then you know that these tasks are done. All remaining tasks take time.

Each task method returns an accepted_rejected status code indicating whether the task was accepted for processing. Tasks may be rejected for a variety of reasons, so it is important to check this code.

The following example shows a wrong way of tasking:

Tibbo BASIC

							'THIS WON'T WORK!
							...
							wln.scan("NET1")
							wln.associate(wln.scanresultbssid,"NET1",wln.scanresultchannel,wln.scanresultbssmode) 'this task will be rejected and skipped over!
						

Three things are wrong here. First, the code does not check if each task is accepted or rejected. Second, it doesn't wait for the first task to complete before starting the second task. Third, "task completed" is not equal to "task completed successfully." For example, the association task will eventually be completed no matter what, but this won't guarantee that you are associated — you must check this separately.

Here is how you should do this:

Tibbo BASIC

							'A BETTER WAY
							...
							if wln.scan("NET1")<>ACCEPTED then
								'task rejected -- react to this
							end if
							while wln.task<>PL_WLN_TASK_IDLE 'waiting for the task to complete...
							wend
							...
							if wln.associate(wln.scanresultbssid,"NET1",wln.scanresultchannel,wln.scanresultbssmode)<>ACCEPTED
								'task rejected -- react to this
							end if
							while wln.task<>PL_WLN_TASK_IDLE 'waiting for the task to complete...
							wend
							If wln.associationstate<>PL_WLN_ASSOCIATED Then
							   'something went wrong and association failed
							End If
							...
						

One problem with this code is that it is blocking. Essentially, it nullifies all our effort that went into building an asynchronous system. Your application is not doing anything useful while the Wi-Fi interface is scanning or associating.

To take advantage of the event-driven nature of TiOS, you can base your execution flow on the on_wln_task_complete event, which is generated each time a task completes. The completed_task argument of the event handler carries the code of the event that has been completed. Therefore, you can advance through your app's execution steps in the following manner:

Tibbo BASIC

							'THIS CODE TAKES FULL ADVANTAGE OF THE EVENT-DRIVEN NATURE OF THE SYSTEM
							 
							'-------------------------------------------
							Sub On_sys_init
							   ...
							   wln.scan("CISCO1") 'start the task and don't wait
							End Sub
							 
							'-------------------------------------------
							Sub On_wln_task_complete(completed_task As pl_wln_tasks)
							   Select Case completed_task
							   Case PL_WLN_TASK_SCAN:
							      'wln.scan() completed
							      If wln.scanresultssid="" Then
							         'failed to find the network, respond to this
							      end if
							      
							      'network discovered, proceed to associating
							      wln.associate(wln.scanresultbssid,"CISCO1",wln.scanresultchannel,wln.scanresultbssmode)
							 
							   Case PL_WLN_TASK_ASSOCIATE:
							      'association task completed, check the result
							      If wln.associationstate<>PL_WLN_ASSOCIATED Then
							           'something went wrong and association failed
							      End If
							   End Select
							End Sub
						