GAP (IO) - Chapter 7: A client side implementation of the HTTP protocol

Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 Ind
[Top of Book] [Contents] [Previous Chapter] [Next Chapter]

[MathJax on]

7 A client side implementation of the HTTP protocol
7.1 Functions for client side HTTP
7.1-1 OpenHTTPConnection
7.1-2 HTTPRequest
7.1-3 HTTPTimeoutForSelect
7.1-4 CloseHTTPConnection
7.1-5 SingleHTTPRequest
7.1-6 CheckForUpdates
7.1-7 ReadWeb

### 7 A client side implementation of the HTTP protocol

The IO package contains an implementation of the client side of the HTTP protocol. The basic purpose of this is of course to be able to download data from web servers from the GAP language. However, the HTTP protocol can perform a much bigger variety of tasks.

#### 7.1 Functions for client side HTTP

##### 7.1-1 OpenHTTPConnection

`‣ OpenHTTPConnection`( hostname, port ) | ( function )

Returns: a record

The first argument hostname must be a string containing the hostname of the server to connect. The second argument port must be an integer in the range from 1 to 65535 and describes the port to connect to on the server.

The function opens a TCP/IP connection to the server and returns a record `conn` with the following components: `conn.sock` is `fail` if an error occurs and otherwise a `File` object linked to the file descriptor of the socket. In case of an error, the component `conn.errormsg` contains an error message, it is otherwise empty. If everything went well then the component `conn.host` is the result from the host name lookup (see `IO_gethostbyname` (3.2-23)) and the component `conn.closed` is set to `false`.

No data is sent or received on the socket in this function.

##### 7.1-2 HTTPRequest

`‣ HTTPRequest`( conn, method, uri, header, body, target ) | ( function )

Returns: a record

This function performs a complete HTTP request. The first argument must be a connection record as returned by a successful call to `OpenHTTPConnection` (7.1-1). The argument method must be a valid HTTP request "method" in form of a string. The most common will be `GET`, `POST`, or `HEAD`. The argument uri is a string containing the URI of the request, which is given in the first line of the request. This will usually be a relative or absolute path name given to the server. The argument header must be a GAP record. Each bound field of this record will we transformed into one header line with the name of the component being the key and the value the value. All bound values must be strings. The argument body must either be a string or `false`. If it is a string, this string is sent away as the body of the request. If no string or an empty string is given, no body will be sent. The header field `Content-Length` is automatically created from the length of the string body. Finally, the argument target can either be `false` or a string. In the latter case, the body of the request answer is written to the file with the name given in target. The `body` component of the result will be the file name in this case. If target is false, the full body of the answer is stored into the `body` component of the result.

The function sends away the request and awaits the answer. If anything goes wrong during the transfer (for example if the connection is broken prematurely), then the component `statuscode` of the resulting record is 0 and the component `status` is a corresponding error message. In that case, all other fields may or may not be bound to sensible values, according to when the error occurred. If everything goes well, then `statuscode` and `status` are bound to the corresponding values coming from the request answer. `statuscode` is transformed into a GAP integer. The header of the answer is parsed, transformed into a GAP record, and stored into the component `header` of the result. The `body` component of the result record is set as described above. Finally, the `protoversion` component contains the HTTP protocol version number used by the server as a string and the boolean value `closed` indicates, whether or not the function has detected, that the connection has been closed by the server. Note that by default, the connection will stay open, at least for a certain time after the end of the request.

See the description of the global variable `HTTPTimeoutForSelect` (7.1-3) for rules how timeouts are done in this function.

Note that if the method is `HEAD`, then no body is expected (none will be sent anyway) and the function returns immediately with empty body. Of course, the `Content-Length` value in the header is as if it the request would be done with the `GET` method.

##### 7.1-3 HTTPTimeoutForSelect

`‣ HTTPTimeoutForSelect` | ( global variable )

This global variable holds a list of length two. By default, both entries are `fail` indicating that `HTTPRequest` (7.1-2) should never timeout and wait forever for an answer. Actually, the two values in this variable are given to the `IO_Select` (4.3-3) function call during I/O multiplexing. That is, the first number is in seconds and the second in milliseconds. Together they lead to a timeout for the HTTP request. If a timeout occurs, an error condition is triggered which returns a record with status code 0 and status being the timeout error message.

You can change the timeout by accessing the two entries of this write protected list variable directly.

##### 7.1-4 CloseHTTPConnection

`‣ CloseHTTPConnection`( conn ) | ( function )

Returns: nothing

Closes the connection described by the connection record conn. No error can possibly occur.

##### 7.1-5 SingleHTTPRequest

`‣ SingleHTTPRequest`( hostname, port, method, uri, header, body, target ) | ( function )

Returns: a record

The arguments are as the corresponding ones in the functions `OpenHTTPConnection` (7.1-1) and `HTTPRequest` (7.1-2) respectively. This function opens an HTTP connection, tries a single HTTP request and immediately closes the connection again. The result is as for the `HTTPRequest` (7.1-2) function. If an error occurs during the opening of the connection, the `statuscode` value of the result is 0 and the error message is stored in the `status` component of the result.

The previous function allows for a very simple implementation of a function that checks, whether your current GAP installation is up to date:

##### 7.1-6 CheckForUpdates

`‣ CheckForUpdates`( ) | ( function )

Returns: nothing

This function has been removed, as it only worked over the insecure HTTP protocol, but not over HTTPS; and the relevant webservice these days only works over HTTPS. If you relied on this functionality, please take a look at the PackageManager package, see https://gap-packages.github.io/PackageManager/.

##### 7.1-7 ReadWeb

`‣ ReadWeb`( URL ) | ( function )

Returns: nothing

This function downloads the file from the given uniform resource locator URL using the HTTP protocol and reads the contents into GAP using `Read` (Reference: Read).

Note that this can execute arbitrary code on your machine with the privileges of the GAP job running, so you should be very careful what files you download and execute. You have been warned!

[Top of Book] [Contents] [Previous Chapter] [Next Chapter]
Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 Ind

generated by GAPDoc2HTML