How to use tsNetGet to retrieve data asynchronously
For many applications, it is helpful if data can be retrieved from a website in the background as it means that the end user is less aware of any delay caused by the time that it takes the data to download.
To help achieve this, the tsNet library provides a range of asynchronous functions that return immediately so that execution of the application's code can continue. A callback message is then sent when the transfer is complete.
In this example, we retrieve the exchange rate between the Australian and US dollar using the asynchronous command tsNetGet. Before the data is retrieved, the application informs the user that their request in progress.
Lay out the Stack
Create a new stack then drag a button and two fields onto it.
Set the name of the fields to "Output1" and "Output2".
Save this stack.
Create the Script
Edit the script of the button that you placed on the stack by right clicking on the button and selecting "edit script".
Add the following code.
on mouseUp pButtonNumber
-- Note that when using tsNetGet we must specify a connection ID (any arbitrary value) and a handler to
-- call when the transfer is completed, in this case we want it to call "tsNetGetFinished".
put tsNetGet("myGetRequest", "http://api.fixer.io/latest?base=USD", tHeaders, "tsNetGetFinished") into tResult
-- If tResult contains anything at this point, there is an error in the parameters sent to the tsNetGet call.
if tResult is not empty then
-- Inform the user of the error
put "Error in tsNetGet call:" && tResult
-- tResult must be empty at this point, so let the user know the call has been successful.
put "tsNetGet has been issued, awaiting response" into field "Output1"
on tsNetGetFinished pID, pResult, pBytes, pCurlCode
put cr & "tsNetGet request has completed, processing data" after field "Output1"
-- If pCurlCode is anything other than 0, the request has not been successful.
-- pResult will be 200 (the HTTP response code for a successful transfer) if
-- tsNetGet was able to retrieve the data
-- If either of these are not the case, we will inform the user
if pCurlCode is not 0 or pResult is not 200 then
put "Could not retrieve data from site" into field "Output2"
-- Retrieve any data returned by tsNetGet
put tsNetRetrData(pID, tError) into tData
-- The retrieved data is in JSON format, convert to a normal LiveCode array
put JSONtoArray(tData) into tArray
-- Display the appropriate currency rate in the "Output" field
put "$1.00 USD dollar is currently $" & tArray["rates"]["AUD"] && "AUD dollars" into field "Output2"
-- Tidy up the resources used by the tsNetGet call:
Switch to Run mode and click the button.
The tsNet library provides asynchronous and synchronous versions for the majority of the functions that it provides. Each asynchronous function requires a connection identifier and a callback message to be specified that will be sent to the object that issued the command when the transfer is completed or an error occurs.
In all cases, the callback message is sent with the same four parameters. These parameters include:
- pID - the user specified connection identifier for the transfer that is passed as the first parameter to the asynchronous function.
- pResult - the last status code returned from the server to the request.
- pBytes - the number of bytes of data that was transferred.
- pCurlCode - any error code that is returned by the underlying libcurl library that tsNet uses.
It is important to note that the first parameter (pID) to the callback message is also the first parameter to the asynchronous function call (in this example, to the function tsNetGet). The value of this parameter is arbitrary and is used to match the initial request to the corresponding callback message within any code.
More detail about these callback parameters can be found in the LiveCode dictionary.