Mac Home Automation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====LoadURL====
Sends an asynchronous web request and returns the result into a special handler in your script. Unlike calling “CURL” from a “do shell script” command this will not wait for the response inline and hang up the entire program while you wait. So you have to write your script in 2 parts. One that starts the request and another that receives the data and does whatever you need to with it. If the request is just to send some data and you do not require a response you can ignore that portion.

loadURL can connect to secure web sites over SSL by just making sure the URL parameter begins with "https://“ instead of just “http://“

As of XTension version 9.4 the loadURL command now supports the 1.3 version of TLS security required by some sites and also adds digest authentication as an automatic response to sites or devices that require that.

===Usage:===
**LoadURL** (text: the URL to connect to. ie: “https://www.apple.com:80/?query=what”)\\
The url parameter is required.

===Optional Parameters:===
  * **timeout** (number: the number of seconds to wait before returning an error. Defaults to 30 seconds)
  * **user** (text: if required for basic or digest authentication)
  * **password** (text: if required for basic or digest authentication)
  * **post data** (list: an applescript list of name=value pairs to be POSTED to the server. To send GET parameters include them in the url string as shown above. The list would look something like {“name=value”, “name2=value2”, “name2=value3”,...} )
  * **callback script** (text: the name of the global script to send the results to) If you leave this option out but include the handler name then the (thisScript) property will be used to try to call back into the same script that ran the loadURL command.
  * **callback handler** (text: the name of the handler in the global script handler to send the response, or error, to.)
  * **custom request** (text: a request type other than GET or POST) optional, if you need to send an HTTP request other than GET or PUT set the value here. If you need to send custom PUT or POST data that isn’t form encoded use the **put data** parameter below.
  * **follow redirects** (boolean: should the request be repeated if the server responds with a redirect) This defaults to true so by specifying “without follow redirects” you can stop it from trying to follow them.
  * **logging debug data** (boolean: logs all the communication and all the protocol negotiation data) Optional. Defaults to false, turn it on by adding “with logging debug data” to the command. Logs absolutely everything to the log. Good for debugging why something isn’t responding but not good to leave setup all the time.
  * **put data** (text: optional) if included the post type will default to PUT and the block of data that you specify in this string will be sent to the server. If you change the request type via the custom request handler above then you can use this to send non-form encoded blocks of any data to the server.
  * **extra headers** (list: optional) an applescript list of text items that will be added to the headers being sent.
  * **force http1** (boolean: optional) add “with force http1” to force the connection to be made using the HTTP1.0 protocol. This can be useful if you are connecting to embedded devices that may not handle the Continue headers or chunked transfer which can be difficult for such things, or if you are talking to some older API’s that also do not support the same.
===Callback Handler Info:===

the callback handler can be in any script. It may make sense to place it in the same global script that started the process by running the loadURL command in the first place. It’s name can be anything as long as it’s a valid applescript handler name, so no spaces or non-letter characters. It will have 2 parameters. The first is a number and will contain the return code from the server, or a -1 if there was a timeout. The second parameter is the text result of the request. The callback script and handler are optional parameters. If you do not need to process the reply or aren’t interested in errors then you can leave those parameters out of the loadURL command and the results will be ignored.

an example callback handler:

<code>
on myCallback( theResult, theData, theTime)
  write log “the request took: “ & theTime & “ milliseconds to complete"
  if theResult is -1 then
    write log “there was a timeout trying to connect to my server” color red
  else if theResult is 200 then
    write log “my server replied with “ & theData
  else
    write log “there was an error returned from the server: “ & theResult
  end if
end myCallback
</code>
===Examples:===
<code>
LoadURL “https://www.apple.com/?these=are&get=parameters” timeout 120 post data {“name=value”, “name=value”} callback handler “gotResult"
</code>

<code>
LoadURL “http://some.arduino.local/api/on” with force http1
</code>

===History===
  * **put data** parameter was added in XTension 9.4.7
  * **custom request** parameter was added in XTension v9.4
  * **follow redirects** parameter was added in XTension v9.4
  * **logging debug data** parameter was added in XTension v9.4
  * **force http1** parameter was added in v9.4.23
Mac Home Automation

User Tools

Site Tools

Page Tools
