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.
‣ 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.
‣ 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.
‣ 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.
‣ CloseHTTPConnection( conn ) | ( function ) |
Returns: nothing
Closes the connection described by the connection record conn. No error can possibly occur.
‣ 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:
‣ 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/.
‣ 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!
generated by GAPDoc2HTML