LiveCode LessonsHow To - Step-By-Step Guides To Tasks In LiveCode ArticlesHow to use tsNetPost to perform a HTTP POST with callbacks

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:

  1. pID - The value of this parameter is the user defined value passed as the first parameter to the tsNetPost function.  In this example - "connectionA"
  2. 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....).
  3. pBytes - This is the number of bytes that have been transferred
  4. 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.

Sample Stacks

Another example LiveCode stack can be found here that sends multiple asynchronous HTTP POST requests and displays the results once they have all completed.

0 Comments

Add your comment

E-Mail me when someone replies to this comment