<h3>7 <span class="Heading">A client side implementation of the HTTP protocol</span></h3>
<p>The <strong class="pkg">IO</strong> 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 <strong class="pkg">GAP</strong> language. However, the HTTP protocol can perform a much bigger variety of tasks.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ OpenHTTPConnection</code>( <var class="Arg">hostname</var>, <var class="Arg">port</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>Returns: a record</p>
<p>The first argument <var class="Arg">hostname</var> must be a string containing the hostname of the server to connect. The second argument <var class="Arg">port</var> must be an integer in the range from <span class="SimpleMath">1</span> to <span class="SimpleMath">65535</span> and describes the port to connect to on the server.</p>
<p>The function opens a TCP/IP connection to the server and returns a record <code class="keyw">conn</code> with the following components: <code class="keyw">conn.sock</code> is <code class="keyw">fail</code> if an error occurs and otherwise a <code class="code">File</code> object linked to the file descriptor of the socket. In case of an error, the component <code class="keyw">conn.errormsg</code> contains an error message, it is otherwise empty. If everything went well then the component <code class="keyw">conn.host</code> is the result from the host name lookup (see <code class="func">IO_gethostbyname</code> (<a href="chap3.html#X7DD25BDC79EE65AD"><span class="RefLink">3.2-23</span></a>)) and the component <code class="keyw">conn.closed</code> is set to <code class="keyw">false</code>.</p>
<p>No data is sent or received on the socket in this function.</p>
<p>This function performs a complete HTTP request. The first argument must be a connection record as returned by a successful call to <code class="func">OpenHTTPConnection</code> (<a href="chap7.html#X7B5588D5856BE6DD"><span class="RefLink">7.1-1</span></a>). The argument <var class="Arg">method</var> must be a valid HTTP request <q>method</q> in form of a string. The most common will be <code class="keyw">GET</code>, <code class="keyw">POST</code>, or <code class="keyw">HEAD</code>. The argument <var class="Arg">uri</var> 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 <var class="Arg">header</var> must be a <strong class="pkg">GAP</strong> 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 <var class="Arg">body</var> must either be a string or <code class="keyw">false</code>. 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 <code class="keyw">Content-Length</code> is automatically created from the length of the string <var class="Arg">body</var>. Finally, the argument <var class="Arg">target</var> can either be <code class="keyw">false</code> or a string. In the latter case, the body of the request answer is written to the file with the name given in <var class="Arg">target</var>. The <code class="keyw">body</code> component of the result will be the file name in this case. If <var class="Arg">target</var> is false, the full body of the answer is stored into the <code class="keyw">body</code> component of the result.</p>
<p>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 <code class="keyw">statuscode</code> of the resulting record is <span class="SimpleMath">0</span> and the component <code class="keyw">status</code> 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 <code class="keyw">statuscode</code> and <code class="keyw">status</code> are bound to the corresponding values coming from the request answer. <code class="keyw">statuscode</code> is transformed into a <strong class="pkg">GAP</strong> integer. The header of the answer is parsed, transformed into a <strong class="pkg">GAP</strong> record, and stored into the component <code class="keyw">header</code> of the result. The <code class="keyw">body</code> component of the result record is set as described above. Finally, the <code class="keyw">protoversion</code> component contains the HTTP protocol version number used by the server as a string and the boolean value <code class="keyw">closed</code> 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.</p>
<p>See the description of the global variable <code class="func">HTTPTimeoutForSelect</code> (<a href="chap7.html#X83526BF378B3D8F2"><span class="RefLink">7.1-3</span></a>) for rules how timeouts are done in this function.</p>
<p>Note that if the <var class="Arg">method</var> is <code class="keyw">HEAD</code>, then no body is expected (none will be sent anyway) and the function returns immediately with empty body. Of course, the <code class="keyw">Content-Length</code> value in the header is as if it the request would be done with the <code class="keyw">GET</code> method.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ HTTPTimeoutForSelect</code></td><td class="tdright">( global variable )</td></tr></table></div>
<p>This global variable holds a list of length two. By default, both entries are <code class="keyw">fail</code> indicating that <code class="func">HTTPRequest</code> (<a href="chap7.html#X80FF9E307BDA0659"><span class="RefLink">7.1-2</span></a>) should never timeout and wait forever for an answer. Actually, the two values in this variable are given to the <code class="func">IO_Select</code> (<a href="chap4.html#X81CA6EE88062010E"><span class="RefLink">4.3-3</span></a>) 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 <span class="SimpleMath">0</span> and status being the timeout error message.</p>
<p>You can change the timeout by accessing the two entries of this write protected list variable directly.</p>
<p>The arguments are as the corresponding ones in the functions <code class="func">OpenHTTPConnection</code> (<a href="chap7.html#X7B5588D5856BE6DD"><span class="RefLink">7.1-1</span></a>) and <code class="func">HTTPRequest</code> (<a href="chap7.html#X80FF9E307BDA0659"><span class="RefLink">7.1-2</span></a>) respectively. This function opens an HTTP connection, tries a single HTTP request and immediately closes the connection again. The result is as for the <code class="func">HTTPRequest</code> (<a href="chap7.html#X80FF9E307BDA0659"><span class="RefLink">7.1-2</span></a>) function. If an error occurs during the opening of the connection, the <code class="keyw">statuscode</code> value of the result is <span class="SimpleMath">0</span> and the error message is stored in the <code class="keyw">status</code> component of the result.</p>
<p>The previous function allows for a very simple implementation of a function that checks, whether your current <strong class="pkg">GAP</strong> installation is up to date:</p>
<p>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 <strong class="pkg">PackageManager</strong> package, see <spanclass="URL"><a href="https://gap-packages.github.io/PackageManager/">https://gap-packages.github.io/PackageManager/</a></span>.</p>
<p>This function downloads the file from the given uniform resource locator <var class="Arg">URL</var> using the HTTP protocol and reads the contents into <strong class="pkg">GAP</strong> using <code class="func">Read</code> (<a href="../../../doc/ref/chap9_mj.html#X8373AC6B7D5F9167"><span class="RefLink">Reference: Read</span></a>).</p>
<p>Note that this can execute arbitrary code on your machine with the privileges of the <strong class="pkg">GAP</strong> job running, so you should be very careful what files you download and execute. You have been warned!</p>
Die Informationen auf dieser Webseite wurden
nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit,
noch Qualität der bereit gestellten Informationen zugesichert.
Bemerkung:
Die farbliche Syntaxdarstellung ist noch experimentell.
