Livecode Wiki

Sets up a callback message to be sent periodically during uploads and downloads.


libURLSetStatusCallback messageName,[objectLongID]


libURLSetStatusCallback "putPercentage",the long ID of me
libURLSetStatusCallback myAction,the long ID of button "Upload"
libURLSetStatusCallback -- turns off status callback messages

Use the libURLSetStatusCallback command if you want to do periodic tasks (such as updating a progress bar) during a data transfer.


  • The messageName is the name of a message to be sent whenever the URLStatus function is updated.
  • The objectLongID is the long ID of the object to send the message to. It isn't required. If no object is passed in then the message will be sent to revLibURL itself and you can handle the message anywhere in the message path

The Internet library periodically updates the URLStatus function during uploads and downloads made with the libURLDownloadToFile, libURLftpUpload, libURLftpUploadFile, put, and load commands, as well as downloads triggered by evaluating an ftp or http URL. Whenever the Internet library updates the URLStatus function, it also sends any callback message you've set up with the libURLSetStatusCallback command.

Callback messages are sent even during blocking uploads and downloads (such as a download started with the put command), so you can use this method to monitor progress for all file transfers.

The callback message is sent with two parameters: the URL and the URL's current status. For example, suppose you execute the following statement to set up a callback message:

 libURLSetStatusCallback "myProgress",the long ID of button "Monitor"

Then suppose you begin an upload with the following command:

 put field "Data" into URL ""

Periodically while the text of the field is being uploaded to the file, a "myProgress" message is sent to button "Monitor". The first parameter sent with "myProgress" is the URL (in this case, the URL is ""), and the second parameter is the current status of that URL. The "myProgress" handler might look like this:

on myProgress theURL,theStatus
  put theStatus into field theURL of stack "Status Monitor"
end myProgress

The URL status parameter is similar to the status returned by the URLStatus function, and is one of the following:

  • "queued": on hold until a previous request to the same site is completed
  • "contacted": the site has been contacted but no data has been sent or received yet
  • "requested": the URL has been requested
  • "loading,bytesReceived,bytesTotal": the URL data is being received
  • "uploading,bytesReceived,bytesTotal": the file is being uploaded to the URL
  • "downloaded": the application has finished downloading the URL
  • "uploaded": the application has finished uploading the file to the URL
  • "error": an error occurred and the URL was not transferred
  • "timeout": the application timed out when attempting to transfer the URL
  • empty: the URL was not loaded, or has been unloaded

The third item (bytesTotal) in the "loading" or "uploading" status report is empty if it is not possible to determine the total file size. (For example, if an ftp server does not support the SIZE command, it's not possible to determine the file size when downloading a file from that server.)

If multiple file transfers are occurring at the same time, a separate callback message is sent for each URL. If you want your callback handler to treat URLs differently (for example, if you want to display separate progress bars for different URLs, or do one thing with http URLs and something else with ftp URLs), use a switch control structure in the handler.

You cannot have two callback messages set up at the same time for uploads and downloads. If you use the libURLSetStatusCallback command to set up a callback message, the Internet library forgets any callback message you previously set up with the command.

To turn off the callback message, use the following statement:

 libURLSetStatusCallback -- no parameters: turns off the message

If you don't include the messageName and objectLongID parameters, the libURLSetStatusCallback command turns off the callback messages so that updating the URLStatus function does not send any messages.

The libURLSetStatusCallback command is part of the Internet library. To ensure that the command works in a standalone application, you must include this custom library when you create your standalone. In the Inclusions section of the Standalone Application Settings window, make sure "Internet Library" is selected in the list of script libraries.

See: Internet library

See Also: libURLDownloadToFile Command, libURLftpUpload Command