Merge pull request #5581 from livecodemichael/feature-emscripten_basic_networking

runrevmark · web-flow · commit 0e78f1608cce · 2017-06-12T19:51:48.000+01:00
[[ Emscripten Networking ]] Added support for load command to HTML5.
diff --git a/docs/dictionary/command/load.lcdoc b/docs/dictionary/command/load.lcdoc
@@ -12,7 +12,7 @@ Associations: internet library
 
 Introduced: 1.0
 
-OS: mac, windows, linux, ios, android
+OS: mac, windows, linux, ios, android, html5
 
 Platforms: desktop, server, mobile
 
@@ -51,8 +51,12 @@ to it using the <URL> <keyword> as usual. When you request the original
 The <callbackMessage> is sent to the <object(glossary)> whose <script> 
 contains the <load> <command>, after the <URL> is <load|loaded>, so you 
 can handle the <callbackMessage> to perform any tasks you want to delay 
-until the URL has been <cache|cached>. Two <parameter|parameters> are 
-sent with the <message> : the <URL> and the <URLStatus> of the <file>.
+until the URL has been <cache|cached>. On iOS, Android and HTML5, four
+<parameter|parameters> are sent with the <message> : the <URL>, the
+<URLStatus> of the <file>, the contents of the <URL> or an error string
+and the total size of the <URL> in bytes. On all other platforms, two
+<parameter|parameters> are sent with the <message> : the <URL> and the
+<URLStatus> of the <file>.
 
 The <load> <command> is non-blocking, so it does not stop the current 
 <handler> while the <download> is completed. The <handler> continues 
@@ -83,18 +87,26 @@ remove it from the <cache>.
 > <Standalone Application Settings> window, make sure the "Internet" 
 > script library is selected.
 
->*Cross-platform note:* On iOS and Android, the <load> <command>
+>*Cross-platform note:* On iOS, Android and HTML5, the <load> <command>
 > is implemented in the engine. Therefore the <Internet library> is not 
-> needed to ensure the <command> works in a mobile 
-> <standalone application>. If included, the <Internet library> 
-> implementation will be used instead of the engine implementation.
+> needed to ensure the <command> works in a <standalone application>. If
+> included, the <Internet library> implementation will be used instead of
+> the engine implementation.
+
+> *Note:* The current HTML5 support for 'load url' is experimental, and
+> will be replaced by a libUrl-like API in a subsequent DP ensuring it has
+> parity with other platforms when 'Internet Library' is used.
 
 > *Note:* When specifying URLs for iOS or Android, you must use the
 > appropriate form that conforms to [RFC
 > 1738](https://tools.ietf.org/html/rfc1738). Ensure that you
 > <URLEncode> any username and password fields appropriately for FTP
 > URLs.
 
+> *Note:* The HTML5 engine only supports HTTP and HTTPs protocols.
+> Also, only URLs from the domain hosting the web page running the HTML5
+> engine can be fetched.
+
 References: unload (command), libURLftpUpload (command),
 libURLDownloadToFile (command), get (command), load (command),
 group (command), function (control structure),
diff --git a/docs/dictionary/message/urlProgress.lcdoc b/docs/dictionary/message/urlProgress.lcdoc
@@ -9,9 +9,9 @@ Sent when updates on ongoing url requests are communicated.
 
 Introduced: 4.6.1
 
-OS: ios, android
+OS: ios, android, html5
 
-Platforms: mobile
+Platforms: mobile, desktop
 
 Example:
 on urlProgress pUrl, pStatus
diff --git a/docs/guides/HTML5 Deployment.md b/docs/guides/HTML5 Deployment.md
@@ -31,12 +31,12 @@ The HTML5 engine in this release of LiveCode has a limited range of features.  Y
 * read and write temporary files in a special virtual filesystem (which is erased when the user navigates away from the page)
 * use LiveCode Builder widgets and extensions
 * interact with JavaScript code in the web page using `do <script> as "JavaScript"`
+* perform basic networking operations using the **load** command
 
 Several important features are not yet supported:
 
 * some `ask` and `answer` message boxes
 * multimedia (the "player" control)
-* networking
 * JavaScript in LiveCode Builder extensions
 
 Two important unsupported features are unlikely to be added in the near future:
diff --git a/docs/notes/feature-emscripten_basic_networking.md b/docs/notes/feature-emscripten_basic_networking.md
@@ -0,0 +1,45 @@
+# HTML5 Basic Networking Support
+
+Basic networking support has been added to the HTML5 engine by way of the **load** command. The HTML5 **load** command functions in the same way as the **load** command on mobile platforms, with a completion message being sent on download, containing the contents of the URL (or any error) and the **urlProgress** message being sent periodically during the request.
+
+**Note: The current HTML5 support for 'load url' is experimental, and will be replaced by a libUrl-like API in a subsequent DP ensuring it has parity with other platforms when 'Internet Library' is used.**
+
+**Note: Only HTTP and HTTPS protocols are supported and URLs can only be fetched from the domain hosting the web page running the HTML5 engine.**
+
+```
+command fetchURL pURL
+   load URL pURL with "loadComplete"
+end fetchURL
+
+on loadComplete pURL, pStatus, pData, pTotal
+   -- pURL - The URL being fetched.
+   --
+   -- pStatus - The status of the URL: One of:
+   --  * downloaded
+   --  * error
+   --
+   -- pData - This will be:
+   --  * the content of the URL, if pStatus is downloaded
+   --  * the error string, if pStatus is error
+   --
+   -- pTotal - The total size of the URL, in bytes.
+end loadComplete
+
+on urlProgress pURL, pStatus, pData, pTotal
+   -- pURL - The URL being fetched.
+   --
+   -- pStatus - The current status of the operation. One of:
+   --  * contacted
+   --  * requested
+   --  * loading
+   --  * downloaded
+   --  * error
+   --
+   -- pData - This will be:
+   --  * the number of bytes fetched, if pStatus is loading
+   --  * the error string, if pStatus is error
+   --  * empty in all other cases
+   --
+   -- pTotal - The total size of the URL, in bytes.
+end urlProgress
+```
diff --git a/engine/src/em-url.js b/engine/src/em-url.js
@@ -51,7 +51,7 @@ mergeInto(LibraryManager.library, {
 			              'number', // int32_t p_total_length
 			              'number', // MCSystemUrlCallback p_callback
 			              'number'], // void *p_context
-			             [loadedLength, callbackPtr, contextPtr]);
+			             [loadedLength, totalLength, callbackPtr, contextPtr]);
 		},
 
 		_postStatusFinished: function(data, callbackPtr, contextPtr) {
@@ -201,7 +201,7 @@ mergeInto(LibraryManager.library, {
 			}
 
 			// Timeout
-			xhr.timeout = timeout;
+			xhr.timeout = timeout * 1000;
 
 			// We want an array buffer response (no string decoding
 			// etc.)
