<doc>
	<legacy_id>1918</legacy_id>
	<name>load</name>
	<type>command</type>

	<syntax>
		<example>load [URL] <i>url</i> [with message <i>callbackMessage</i>]</example>
	</syntax>

	<synonyms>
	</synonyms>

	<summary><glossary tag="download">Downloads</glossary> the <keyword tag="file">file</keyword> specified by a <keyword tag="URL">URL</keyword> to a <glossary tag="cache">cache</glossary> where it can be used by another <glossary tag="handler">handler</glossary>.</summary>

	<examples>
<example>load URL &quot;http://www.example.com/index.html&quot;</example>
<example>load URL myURL with message &quot;downloadComplete&quot;</example>
<example><p>load URL tMyUrl with message &quot;myUrlDownloadFinished&quot;</p></example>
<example><p>on myUrlDownloadFinished</p><p>   answer &quot;Download Complete&quot; with &quot;Okay&quot;</p><p>end myUrlDownloadFinished</p></example>
	</examples>

	<history>
		<introduced version="1.0">Added.</introduced>
		<deprecated version=""></deprecated>
		<removed version=""></removed>
		<changed version="4.6.1">Added Support for Android and iOS.</changed>
	</history>

	<objects>
	</objects>

	<platforms>
		<mac/>
		<windows/>
		<linux/>
		<ios/>
		<android/>
	</platforms>

	<classes>
		<desktop/>
		<server/>
		<web/>
		<mobile/>
	</classes>

	<security>
		<network/>
	</security>


	<classification>
		<category>Networks &amp; Communication</category>
		<category>Standalone Applications</category>
	</classification>

	<references>
		<function tag="libURLLastRHHeaders">libURLLastRHHeaders Function</function>
		<function tag="libURLErrorData">libURLErrorData Function</function>
		<function tag="cachedURLs">cachedURLs Function</function>
		<command tag="get">get Command</command>
		<command tag="libURLDownloadToFile">libURLDownloadToFile Command</command>
		<command tag="libURLftpUpload">libURLftpUpload Command</command>
		<keyword tag="url">url Keyword</keyword>
	</references>

	<description>
	<overview>Use the <b>load</b> <glossary tag="command">command</glossary> to pre-fetch a <keyword tag="file">file</keyword> from the Internet in order to speed up access when using it in an <glossary tag="expression">expression</glossary> with the <keyword tag="URL">URL</keyword> <glossary tag="keyword">keyword</glossary>.</overview>

		<parameters>
  <parameter>
    <name>url</name>
    <description>Is any valid http or ftp URL.</description>
  </parameter>
  <parameter>
    <name>callbackMessage</name>
    <description>Is the name of a message to send after the URL is loaded.</description>
  </parameter>		</parameters>

	<value></value>
	<comments>To use a file that has been downloaded by the <b>load</b> <glossary tag="command">command</glossary>, refer to it using the <keyword tag="URL">URL</keyword> <glossary tag="keyword">keyword</glossary> as usual. When you request the original <keyword tag="URL">URL</keyword>, LiveCode uses the <glossary tag="cache">cached</glossary> <keyword tag="file">file</keyword> automatically.<p></p><p>The <i>callbackMessage</i> is sent to the <glossary tag="object">object</glossary> whose <property tag="script">script</property> contains the <b>load</b> <glossary tag="command">command</glossary>, after the <keyword tag="URL">URL</keyword> is <glossary tag="load">loaded</glossary>, so you can handle the <i>callbackMessage</i> to perform any tasks you want to delay until the URL has been <glossary tag="cache">cached</glossary>. Two <glossary tag="parameter">parameters</glossary> are sent with the <keyword tag="message box">message</keyword>: the <keyword tag="URL">URL</keyword> and the <function tag="URLStatus">URLStatus</function> of the <keyword tag="file">file</keyword>.</p><p></p><p>The <b>load</b> <glossary tag="command">command</glossary> is non-blocking, so it does not stop the current <glossary tag="handler">handler</glossary> while the <glossary tag="download">download</glossary> is completed. The <glossary tag="handler">handler</glossary> continues while the <command tag="load">load</command> <glossary tag="command">command</glossary> downloads the <keyword tag="URL">URL</keyword> in the background. You can monitor the download by checking the <function tag="URLStatus">URLStatus</function> <control_st tag="function">function</control_st> periodically.</p><p></p><p></p><p></p><p><code tag="">  load URL myURL</code></p><p><code tag="">  wait until the URLStatus of myURL is cached </code>-- <code tag="">DON'T DO THIS</code></p><p></p><p>The file is downloaded into a local cache. It does not remain available after the application quits; the purpose of the cache is to speed up access to the specified URL, not to store it permanently. You can use a URL even if it is not in the cache, so use of the <b>load</b> <glossary tag="command">command</glossary> is optional.</p><p></p><p></p><note>Cached <function tag="files">files</function> consume memory. To release this memory after you are finished with a <keyword tag="URL">URL</keyword>, use the <command tag="unload">unload </command> <glossary tag="command">command</glossary> to remove it from the <glossary tag="cache">cache</glossary>.</note><p></p><p><code tag=""><important></code><code tag=""> The </code><b>load</b> <glossary tag="command">command</glossary> is part of the <glossary tag="Internet library">Internet library on desktop platforms</glossary>. To ensure that the <glossary tag="command">command</glossary> works in a <glossary tag="standalone application">standalone desktop application</glossary>, you must include this <glossary tag="LiveCode custom library">custom library</glossary> when you create your <glossary tag="standalone application">standalone</glossary>. In the Inclusions section of the <glossary tag="Standalone Application Settings">Standalone Application Settings</glossary> window, make sure Internet Library is selected in the list of script libraries. The iOS and Android engines do not support 'libUrl' but allows you to use <b>load</b> in the background.</important><p></p><p></p><note>When specifying URLs for iOS and Android, you must use the appropriate form that confirms to the RFC standards. Ensure that you <function tag="URLEncode">URLEncode</function> any username and password fields appropriately for FTP urls.</note><p></p><p><code tag=""><note></code> <code tag="">When included in a</code> <glossary tag="standalone application">standalone application</glossary>, the <glossary tag="Internet library">Internet library</glossary> is implemented as a hidden <command tag="group">group</command> and made available when the <command tag="group">group</command> receives its first <message tag="openBackground">openBackground</message> message. During the first part of the <glossary tag="application">application's</glossary> startup process, before this <keyword tag="message box">message</keyword> is sent, the <b>load</b> <glossary tag="command">command</glossary> is not yet available. This may affect attempts to use this <glossary tag="command">command</glossary> in <message tag="startup">startup</message>, <message tag="preOpenStack">preOpenStack</message>, <message tag="openStack">openStack</message>, or <message tag="preOpenCard">preOpenCard</message> <glossary tag="handler">handlers</glossary> in the <glossary tag="main stack">main stack</glossary>. Once the <glossary tag="application">application</glossary> has finished starting up, the <command tag="start using">library</command> is available and the <b>load</b> <glossary tag="command">command</glossary> can be used in any <glossary tag="handler">handler</glossary>.</note></comments>
	</description>
</doc>