How to use tsNetPost to perform a HTTP POST with callbacks
Using callbacks with tsNet
The tsNet external supports using callbacks for all transfer types. Using callbacks allows your scripts to continue executing without waiting for the transaction to complete.
Once the transfer has completed, the callback handler will be called with a number of parameters that allows the user to identify the connection that has completed.
An example using HTTP POST
To initiate a HTTP POST request in a non-blocking manner, the tsNetPost function can be used. The syntax for this function is:
tsNetPost(pConnectionID, pURL, pHeaders, pPostData, pCallback, [pSettings])
Let us work through an example script that uses this function call so that we can see how to use callbacks with tsNet.
In this example, we will perform the requests inside the mouseUp handler, so here we go!
on mouseUp local tUrl, tPostData, tHeaders, tError put "https://downloads.techstrategies.com.au/tsnet/getentry.php" into tUrl put "key=value" into tPostData put "Content-Type: application/x-www-form-urlencoded" into tHeaders put tsNetPost("connectionA",tUrl,tHeaders,tPostData,"postResponse") into tError end mouseUp
As with the standard libUrl HTTP post, we specify the URL to connect to, the data to POST to the server and any HTTP headers that we want to send in the request. The default "Content-Type" header for POST requests with tsNet is "application/x-www-form-urlencoded", however this script sets that header as an example.
The first parameter to the tsNetPost function is a user defined value that is sent as the first parameter to the callback function which must be sent (by name) as the last parameter to the function (in this case - postResponse). This allows each request to be uniquely identified.
The callback function is passed four parameters:
- pID - The value of this parameter is the user defined value passed as the first parameter to the tsNetPost function. In this example - "connectionA"
- pStatus - For protocols that return a status code (notably HTTP and FTP), this is the status code returned by the server to the last command issued as part of the request. While HTTP requests usually consist of only one command, FTP requests may include multiple commands (changing directory, logging out, etc....).
- pBytes - This is the number of bytes that have been transferred
- pResult - This is the cURL error code that is returned by the underlying library behind tsNet. For successful connections, this will always be 0. You can obtain the full list of possible errors at https://curl.haxx.se/libcurl/c/libcurl-errors.html or obtain a more descriptive error by calling tsNetRetrErr with the value of the pID parameter.
Here is the callback function for this example:
on postResponse pID, pStatus, pBytes, pResult local tError, tData, tResponse if pResult is not 0 then -- If pResult is not 0, then a libcurl error occurred, call tsNetRetrError() to get more detail of the error put tsNetRetrError(pID) into tError answer "Error:" && tError && "while retrieving data for entry" & pID else if the first char of pStatus is not 2 then -- Successful HTTP transactions get a 2xx response code, so error if this is not the case answer "Received HTTP response code" && pStatus && "while retreiving data for entry" & pID else -- Otherwise we have a successful transaction, so retrieve any data that was returned put tsNetRetrData(pID, tError) into tData if tError is not empty then -- This should only happen if the external ran out of memory retrieving the data, or the connection was already closed answer "Error:" && tError && "while retrieving data for entry" & pID end if end if -- Always close the connection to release any memory allocated to the connection tsNetCloseConn pID answer tData end postResponse
Firstly the function checks to see if any cURL error occurred. If so, it retrieves more information about the error by calling tsNetRetrError (passing it the value of pID) and alerting the user of any information it finds.
If no error occurred, we check the status code returned by the HTTP server to ensure we received a successful HTTP response.
Next, assuming no errors and a successful status code, we retrieve the returned HTTP data by calling tsNetRetrData (again passing it the value of pID).
Lastly, we close the connection to release any memory associated with it.
Another example LiveCode stack can be found here that sends multiple asynchronous HTTP POST requests and displays the results once they have all completed.