URLStatus

Typefunction
DictionaryLCS
LibraryLiveCode Script
Syntax
the URLStatus of <url>
URLStatus(<url>)
Associationsinternet library
Summary

Returns the status of uploads and downloads that were started with the load, libURLDownloadToFile, libURLftpUpload, and libURLftpUploadFile commands.

Introduced1.0
Changes

The URLStatus function became part of the Internet library in version 1.1. In previous versions, it was not a library function.

OSmac, windows, linux, web
Platformsdesktop, server
Parameters
NameTypeDescription
url

A URL, or an expression that evaluates to a URL.

Example
the URLStatus of "http://www.example.com/test.html"
wait until URLStatus(field "URL") is "cached"
if URLStatus(myFile) is "error" then get libURLErrorData(myFile)
Values
NameTypeDescription
return

A string describing the current status of the URL operation.

  • 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,<b>bytesReceived</b>,<b>bytesTotal</b>: the URL data is being received; items 2 and 3 of the return value provide progress information
  • uploading,<b>bytesReceived</b>,<b>bytesTotal</b>: the file is being uploaded to the URL; items 2 and 3 of the return value provide progress information
  • cached: the URL is in the cache and the download is complete
  • 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
RelatedKeyword: URL
Glossary: FTP, return, standalone application, cache, command, callback, Standalone Application Settings, upload, download, message, server, handler, LiveCode custom library
Command: post, libURLftpUploadFile, libURLftpUpload, libURLDownloadToFile, load, libURLSetStatusCallback
Function: libURLLastRHHeaders, libURLErrorData, URLStatus, cachedURLs
Library: Internet library
Control Structure: function
Securitynetwork
Description

Use the URLStatus function to check the progress of an upload or download.

You can check the cachedURLs function to determine whether a URL has already been downloaded. The URL is not placed in the cachedURLs until the download is complete, however, so you must use the URLStatus function to check a pending download or one that has been started but not finished.

Tip: To update a progress indicator or perform other tasks during uploads and downloads, use the libURLSetStatusCallback command to automatically send a callback message every time the URLStatus function is updated. You can then write a handler for this message that performs whatever tasks are needed.

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 an error occurs during downloading, the URLStatus function returns "error". You can get the error message using the libURLErrorData function.

Important: The URLStatus function is part of the Internet library. To ensure that the function works in a standalone application, you must include this custom library when you create your standalone. In the Inclusions pane of the Standalone Application Settings window, make sure the "Internet" script library is selected.

Tagsnetworking