Topic: APLX Help : System Classes : List of Classes : HTTPClient [ Previous | Next | Contents | Index | APL Home ]

HTTPClient

Description

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 ¯1. In this case, the status property will contain more details on the underlying error.

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.

For example:

      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

Informational

100	Continue
101	Switching Protocols

Successful

200	OK
201	Created
202	Accepted
203	Non-Authoritative Information
204	No Content
205	Reset Content
206	Partial Content

Redirection

300	Multiple Choices
301	Moved Permanently
302	Moved temporarily
303	See Other
304	Not Modified
305	Use Proxy
306	(Unused)
307	Temporary Redirect

Client Error

400	Bad Request
401	Unauthorized
402	Payment Required
403	Forbidden
404	Not Found
405	Method Not Allowed
406	Not Acceptable
407	Proxy Authentication Required
408	Request Timeout
409	Conflict
410	Gone
411	Length Required
412	Precondition Failed
413	Request Entity Too Large
414	Request-URI Too Long
415	Unsupported Media Type
416	Requested Range Not Satisfiable
417	Expectation Failed

Server Error

500	Internal Server Error
501	Not Implemented
502	Bad Gateway
503	Service Unavailable
504	Gateway Timeout
505	HTTP Version Not Supported

Example

     ∇DEMO_HTTPClient;errcode;mimetype;data;address;HTTP
[1]   ⍝ Sample function demonstrating use of the HTTPClient object
[2]   HTTP←'⎕' ⎕NEW 'HTTPClient'
[3]   ⍞←'Enter web address (for example, http://www.bbc.co.uk): '
[4]   address←⎕DBR ⍞
[5]   (errcode mimetype data)←HTTP.Get address
[6]   :If (errcode<200)∨(errcode>300)
[7]     'An error occurred, code = ',errcode
[8]   :Else
[9]     'Got the page OK.'
[10]    'Asked for:  ',address
[11]    'Actual URL: ',HTTP.url
[12]    'MIME Type:  ',mimetype
[13]    'Size:       ',⍕⍴data
[14]    'Cookie:     ',HTTP.cookie
[15]  :EndIf
     ∇

Properties

children class cookie data events methods name opened password properties proxy referrer self status style tie timeout url user

Methods

Close Create Delete Get Head New Open Post Send Set Trigger

Callbacks

onClose onDestroy onOpen onSend

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.