<doc>

<legacy_id>2162</legacy_id>

<name>https</name>

<type>keyword</type>

<syntax>

</syntax>

<library>Internet library</library>

<objects>

</objects>

<synonyms>

</synonyms>

<classification>

</classification>

<references>

<function tag="libURLErrorData">libURLErrorData Function</function>

<command tag="libURLSetCustomHTTPHeaders">libURLSetCustomHTTPHeaders Command</command>

</references>

<history>

<introduced version="2.5">Added.</introduced>

</history>

<platforms>

<mac/>

<windows/>

<linux/>

<ios/>

<android/>

</platforms>

<classes>

<desktop/>

<server/>

<web/>

<mobile/>

</classes>

<security>

<network/>

</security>

<summary>Used as a <keyword tag="URL">URL</keyword> type with such <glossary tag="command">commands</glossary> as <command tag="put">put</command> and <command tag="get">get</command> to designate a <keyword tag="file">file</keyword> on the World Wide Web.</summary>

<examples>

<example>set the htmlText of field 1 to URL "https://example.org/data.html"</example>

<example>put URL "https://www.example.com/output?this=that" into testData</example>

<example>put line 2 of URL "https://www.example.com/stuff/" into testDate</example>

</examples>

<description>

<p>Use the <b>http</b> <glossary tag="keyword">keyword</glossary> to work with <function tag="files">files</function> on the Web.</p><p/><p><b>Comments:</b></p><p>The URL scheme "http" indicates information located on a web server. An <b>http</b> <keyword tag="URL">URL</keyword> consists of:</p><p> 1. The string "https://"</p><p> 2. An optional user name and password, separated by a colon (:) and followed by "@"</p><p> 3. The name of the server (for instance, "example.net") followed by a slash</p><p> 4. The location of the resource (often, a file path).</p><p/><p>Here are some examples of valid <b>https</b> <glossary tag="URL">URLs</glossary>:</p><p/><p><b>https://www.example.com</b></p><p>The main page for the server "www.example.com"</p><p/><p><b>https://www.example.com/directory/</b></p><p>A directory on the server</p><p/><p><b>https://www.example.com/directory/file.html</b></p><p>A file on the server</p><p/><p><b>https://user:[email protected]/file.txt</b></p><p>A file accessed by a user name and password</p><p/><p><b>https://www.example.com/directory/stuff.html?list=yes</b></p><p>A page generated by a query--possibly generated by a CGI</p><p/><p><img src="202653"/> <b>Important!</b> If your user name or password contains any of the characters ":", "@", "/", ".", or "|", use the <b>URLEncode</b> <control_st tag="function">function</control_st> to safely encode the user name or password before putting them into the <keyword tag="URL">URL</keyword>. The following example constructs a <keyword tag="URL">URL</keyword> for a user whose password contains the "@" character:</p><p/><p> put "name" into userName</p><p> put "[email protected]" into userPassword</p><p> put "https://" &amp; userName &amp; ":" &amp; URLEncode(userPassword) \</p><p> &amp; "@www.example.net/index.html" into fileURLToGet</p><p> get URL fileURLToGet</p><p/><p>An <b>http</b> <keyword tag="URL">URL</keyword> is a <glossary tag="container">container</glossary>, and you can use the <glossary tag="expression">expression</glossary> URL <i>httpURL</i> in any statement where any other <glossary tag="container">container</glossary> type is used. When you get the <function tag="value">value</function> of an <b>http</b> <keyword tag="URL">URL</keyword>, LiveCode downloads the <keyword tag="URL">URL</keyword> from the <glossary tag="server">server</glossary>. (If you have previously <glossary tag="cache">cached</glossary> the URL with the <command tag="load">load</command> <glossary tag="command">command</glossary>, it fetches the <keyword tag="URL">URL</keyword> from the <glossary tag="cache">cache</glossary>.)</p><p/><p>If an error occurs during transfer of the data, the error is placed in the <b>result</b> <control_st tag="function">function</control_st>. The first <keyword tag="word">word</keyword> returned by the <function tag="result">result</function> <control_st tag="function">function</control_st> is "error", followed (where appropriate) by the text of the error message returned by the HTTP <glossary tag="server">server</glossary>, including the server response code.</p><p/><p><img src="202653"/> <b>Important!</b> If there is an error downloading an <b>https</b> <keyword tag="URL">URL</keyword>, the <keyword tag="URL">URL</keyword> <glossary tag="container">container</glossary> does not necessarily <glossary tag="evaluate">evaluate</glossary> to empty. Most <keyword tag="http">HTTP</keyword> <glossary tag="server">servers</glossary> send an error page when the file is not found or another error occurs, and the URL <glossary tag="container">container</glossary> will evaluate to the contents of this page. Before using the data in a URL <glossary tag="container">container</glossary>, check the <function tag="result">result</function> to make sure it is empty and there was no error.</p><p/><p><b>Note:</b> Transferring a <keyword tag="URL">URL</keyword> by using it in an <glossary tag="expression">expression</glossary> is a <glossary tag="blocking">blocking</glossary> operation: that is, the <glossary tag="handler">handler</glossary> pauses until LiveCode is finished getting the <keyword tag="URL">URL</keyword>. Since contacting a <glossary tag="server">server</glossary> may take some time due to network lag, <keyword tag="URL">URL</keyword> operations may take long enough to be noticeable to the user.</p><p/><p><img src="202653"/> <b>Important!</b> If a <glossary tag="blocking">blocking</glossary> operation involving a <keyword tag="URL">URL</keyword> (using the <command tag="put">put</command> <glossary tag="command">command</glossary> to <glossary tag="upload">upload</glossary> a <keyword tag="URL">URL</keyword>, the <command tag="post">post</command> <glossary tag="command">command</glossary>, the <command tag="delete URL">delete URL</command> <glossary tag="command">command</glossary>, or a <glossary tag="statement">statement</glossary> that gets an <keyword tag="ftp">ftp</keyword> or <keyword tag="http">HTTP</keyword> <keyword tag="URL">URL</keyword>) is going on, no other <glossary tag="blocking">blocking</glossary> <keyword tag="URL">URL</keyword> operation can start until the previous one is finished. If you attempt to use a <keyword tag="URL">URL</keyword> in an <glossary tag="expression">expression</glossary>, or put data into a <keyword tag="URL">URL</keyword>, while another <glossary tag="blocking">blocking</glossary> <keyword tag="URL">URL</keyword> operation is in progress, the <function tag="result">result</function> is set to "Error Previous request not completed".</p><p/><p>Downloading a URL does not prevent other messages from being sent during the download: the current handler is blocked during the download, but other handlers are not. This means that if, for example, your application has a button that downloads a URL, the user might click the button again (or click another <keyword tag="button">button</keyword> that <glossary tag="download">downloads</glossary> another <keyword tag="URL">URL</keyword>) while the first <keyword tag="URL">URL</keyword> is still being <glossary tag="download">downloaded</glossary>. In this case, the second <glossary tag="download">download</glossary> is not performed and the <function tag="result">result</function> is set to "error Previous request has not completed." To avoid this problem, you can set a flag while a URL is being <glossary tag="download">downloaded</glossary>, and check that <glossary tag="flag">flag</glossary> when trying to <glossary tag="download">download</glossary> <glossary tag="URL">URLs</glossary> to make sure that there is not already a current <glossary tag="download">download</glossary> in progress.</p><p/><p>The following example shows how to set a flag in a global variable to prevent multiple downloads. The variable "downloadInProgress" is set to true while a download is going on, and back to false when the download concludes. If the user clicks the button again while the download is still going on, the handler simply beeps:</p><p/><p> on mouseUp</p><p> global downloadInProgress</p><p> if downloadInProgress then</p><p> beep</p><p> exit mouseUp</p><p> end if</p><p> put true into downloadInProgress <i>-- about to start</i></p><p> put URL (field "Page to get") into field "Command Result"</p><p> put false into downloadInProgress <i>-- finished</i></p><p> end mouseUp</p><p/><p>For technical information about URLs and the <b>https</b> <keyword tag="URL">URL</keyword> scheme, see RFC 1630 at &lt;<u>http://www.ietf.org/rfc/rfc1630.txt</u>&gt;.</p><p/><p><img src="202653"/> <b>Important!</b> The <b>https</b> <glossary tag="keyword">keyword</glossary> is part of the <glossary tag="Internet library">Internet library</glossary> and the SSL &amp; Encryption library. To ensure that the <glossary tag="keyword">keyword</glossary> works in a <glossary tag="standalone application">standalone 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" and "SSL &amp; Encryption" is selected in the list of script libraries.</p><p/><p><b>Note:</b> When included in a <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>http</b> <glossary tag="keyword">keyword</glossary> is not yet available. This may affect attempts to use this <glossary tag="keyword">keyword</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>http</b> <glossary tag="keyword">keyword</glossary> can be used in any <glossary tag="handler">handler</glossary>.</p>

</description>

</doc>