## 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:

| Portions of this software are Copyright (c) 1993 - 2003, Chad Z. Hower (Kudzu) and the Indy Pit Crew - http://www.IndyProject.org/.

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.

Topic: APLX Help : System Classes : List of Classes : HTTPClient

[ Previous | Next | Contents | Index ]