How to use tsNetGet to retrieve data asynchronously
Introduction
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", "https://jsonplaceholder.typicode.com/todos", 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
else
-- 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"
end if
end mouseUp
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"
else
-- 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 "Line 1:" && tArray["1"]["title"] into field "Output2"
end if
-- Tidy up the resources used by the tsNetGet call:
tsNetCloseConn pID
end tsNetGetFinished
Test
Switch to Run mode and click the button.
More information
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.
Molly Feanny
When I tried out this tutorial, the data couldn't be received and displayed. With a bit of research, it turns out that you need to get an account at https://fixer.io and get an API access key beforehand.
Charles Warwick
Hi Molly,
Thanks for your feedback, we will update this lesson shortly.
Regards,
Charles