The HTTPClient object allows your APLX applications to retrieve information over the internet using the HTTP protocol used by the World Wide Web. For example, you can use it to download the HTML text of a web page, or to download a binary file from a web site. It should be created as a top-level object, i.e. not as the child of a Window or other control.
Using the Get method
The HTTPClient object is very easy to use. In most cases, all you need to do is call the Get method to retrieve the data associated with a web address (URL). This takes as an argument a character vector containing the URL to retrieve (e.g. 'http://www.microapl.co.uk/apl/index.html').
The result is a three element nested vector.
The first element is an integer scalar. If the web server was successfully contacted, this will be the HTTP return code. A number in the range 200 to 299 indicates success. A number in the range 400 to 499 indicates an error, such as 404 meaning 'page not found'. (See below for a list of HTTP return codes.) If the web server could not be contacted, for example because the server name was not found, or your network connection has failed, the return code will be
The second element is a character vector indicating the MIME type of the returned data, for example 'image/gif' or 'text/plain'.
The third element is a character vector containing the data. This will usually be the HTML text of the web page (possibly with embedded carriage returns), translated to the APLX character set. For a binary file or image, or any data for which the MIME type does not begin with 'text', it will be the raw bytes returned by the web-server, without translation. If there is no data, or an error occurs, this will be an empty vector.
HTTP←'⎕' ⎕NEW 'HTTPClient' (errcode mimetype text) ← HTTP.Get 'http://www.microapl.co.uk/apl' errcode 200 mimetype text/html ⍴text 10254 100↑text <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <!-- $$PAGE_TITLE$$='APLX<sup><small
Using the Post and Head methods
The Post and Head methods are similar to Get, and have the same syntax, arguments, and result structure. Post is used for HTML forms and pages where you need to send data to the web server; the argument has the data appended to the URL separated by a question mark, with & substituted for space (for example, 'http://www.blah.com?request=doit&code=101').
Head is the same as Get, except that it returns the HTTP header associated with the page, not the page itself. For example:
(errcode mimetype text) ← HTTP.Head 'http://www.microapl.co.uk/apl' errcode 200 mimetype text/html text Server: Zeus/4.2 Date: Wed, 09 Feb 2005 12:19:41 GMT Content-Type: text/html Content-Length: 10437 Accept-Ranges: bytes Last-Modified: Thu, 07 Oct 2004 11:35:34 GMT
Properties of the HTTPClient object
user and password: Set the user name and password for web pages which require login, as character vectors.
style: An integer scalar, which is the sum of the codes 1 meaning 'Allow Cookies' and 2 meaning 'Allow Redirects'. The default is 3.
timeout: An integer scalar, which is the timeout value in milliseconds.
proxy: Some corporate networks may require you to send HTTP requests via a 'proxy server'. If this is the case, you need to set the proxy property as a nested vector of (Proxy address) (Port number). Your network administrator will be able advise on whether this applies to your network. The default is an empty vector, meaning no proxy server is required.
referrer: This property contains the Referrer URL which will be passed to the web server when you access a page using the HTTPClient object. It is typically used by web administrators to keep track of the page which contained the link by which a given user reached the web-site. Normally you can leave this as an empty vector.
status: (Read-only) This returns a two-element integer vector. The first element is reserved for future use. The second element is the latest error code returned by the underlying operating-system networking code. (See for example, the Windows documentation and include file 'winsock.h' for details on these error codes.)
url: (Read-only) This property contains the actual Uniform Resource Location (i.e. web page address) which has just been retrieved. This may not be the same as the page you requested, because the request may have been re-directed.
cookie: (Read-only) Once you have used the Get method to retrieve the a page from a web-site, this property contains the text of any 'cookie' sent by the web server. It will be an empty vector if no 'cookie' was sent. Under Windows and Linux, the cookie will automatically be sent back to the web server if you access the same site again, unless you have disallowed cookies using the style property. Under MacOS, cookies are always disallowed.
HTTP Return Codes
∇DEMO_HTTPClient;errcode;mimetype;data;address;HTTP  ⍝ Sample function demonstrating use of the HTTPClient object  HTTP←'⎕' ⎕NEW 'HTTPClient'  ⍞←'Enter web address (for example, http://www.bbc.co.uk): '  address←⎕DBR ⍞  (errcode mimetype data)←HTTP.Get address  :If (errcode<200)∨(errcode>300)  'An error occurred, code = ',errcode  :Else  'Got the page OK.'  'Asked for: ',address  'Actual URL: ',HTTP.url  'MIME Type: ',mimetype  'Size: ',⍕⍴data  'Cookie: ',HTTP.cookie  :EndIf ∇
Licensing (Windows and Linux versions)
In the Windows and Linux versions of APLX, the HTTPClient object is based on the Indy networking classes. The following notices apply to these versions:
THIS SOFTWARE IS PROVIDED BY Chad Z. Hower (Kudzu) and the Indy Pit Crew "AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Copyright © 1996-2010 MicroAPL Ltd