  
  [1m[4m[31m7. A client side implementation of the HTTP protocol[0m
  
  The  [1mIO[0m  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  [1mGAP[0m  language. However, the HTTP protocol can
  perform a much bigger variety of tasks.
  
  
  [1m[4m[31m7.1 Functions for client side HTTP[0m
  
  [1m[4m[31m7.1-1 OpenHTTPConnection[0m
  
  [1m[34m> OpenHTTPConnection( [0m[22m[34mhostname, port[0m[1m[34m ) _____________________________[0mfunction
  [1mReturns:[0m  a record
  
  The  first argument [22m[34mhostname[0m must be a string containing the hostname of the
  server  to connect. The second argument [22m[34mport[0m 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
  [22m[32mconn[0m with the following components: [22m[32mconn.sock[0m is [22m[32mfail[0m if an error occurs and
  otherwise a [22m[32mFile[0m object linked to the file descriptor of the socket. In case
  of  an  error,  the component [22m[32mconn.errormsg[0m contains an error message, it is
  otherwise empty. If everything went well then the component [22m[32mconn.host[0m is the
  result  from  the  host  name lookup (see [1m[34mIO_gethostbyname[0m ([1m3.2-21[0m)) and the
  component [22m[32mconn.closed[0m is set to [22m[32mfalse[0m.
  
  No data is sent or received on the socket in this function.
  
  [1m[4m[31m7.1-2 HTTPRequest[0m
  
  [1m[34m> HTTPRequest( [0m[22m[34mconn, method, uri, header, body, target[0m[1m[34m ) ___________[0mfunction
  [1mReturns:[0m  a record
  
  This function performs a complete HTTP request. The first argument must be a
  connection  record  as  returned  by a successful call to [1m[34mOpenHTTPConnection[0m
  ([1m7.1-1[0m).  The  argument [22m[34mmethod[0m must be a valid HTTP request "method" in form
  of a string. The most common will be [22m[32mGET[0m, [22m[32mPOST[0m, or [22m[32mHEAD[0m. The argument [22m[34muri[0m 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 [22m[34mheader[0m must be a [1mGAP[0m 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  [22m[34mbody[0m  must  either be a string or [22m[32mfalse[0m. 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
  [22m[32mContent-Length[0m  is automatically created from the length of the string [22m[34mbody[0m.
  Finally,  the argument [22m[34mtarget[0m can either be [22m[32mfalse[0m or a string. In the latter
  case,  the  body  of the request answer is written to the file with the name
  given  in  [22m[34mtarget[0m. The [22m[32mbody[0m component of the result will be the file name in
  this  case.  If  [22m[34mtarget[0m is false, the full body of the answer is stored into
  the [22m[32mbody[0m 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 [22m[32mstatuscode[0m of the resulting record is 0 and
  the  component  [22m[32mstatus[0m  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 [22m[32mstatuscode[0m and [22m[32mstatus[0m are
  bound to the corresponding values coming from the request answer. [22m[32mstatuscode[0m
  is  transformed  into  a  [1mGAP[0m  integer.  The header of the answer is parsed,
  transformed  into  a [1mGAP[0m record, and stored into the component [22m[32mheader[0m of the
  result.  The  [22m[32mbody[0m component of the result record is set as described above.
  Finally,  the  [22m[32mprotoversion[0m  component  contains  the  HTTP protocol version
  number  used  by  the  server  as  a  string  and  the  boolean value [22m[32mclosed[0m
  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 [1m[34mHTTPTimeoutForSelect[0m ([1m7.1-3[0m) for
  rules how timeouts are done in this function.
  
  Note that if the [22m[34mmethod[0m is [22m[32mHEAD[0m, then no body is expected (none will be sent
  anyway) and the function returns immediately with empty body. Of course, the
  [22m[32mContent-Length[0m  value  in  the  header is as if it the request would be done
  with the [22m[32mGET[0m method.
  
  [1m[4m[31m7.1-3 HTTPTimeoutForSelect[0m
  
  [1m[34m> HTTPTimeoutForSelect_______________________________________[0mglobal variable
  
  This  global  variable  holds a list of length two. By default, both entries
  are  [22m[32mfail[0m  indicating that [1m[34mHTTPRequest[0m ([1m7.1-2[0m) should never timeout and wait
  forever  for  an answer. Actually, the two values in this variable are given
  to the [1m[34mIO_Select[0m ([1m4.3-3[0m) 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.
  
  [1m[4m[31m7.1-4 CloseHTTPConnection[0m
  
  [1m[34m> CloseHTTPConnection( [0m[22m[34mconn[0m[1m[34m ) ______________________________________[0mfunction
  [1mReturns:[0m  nothing
  
  Closes  the connection described by the connection record [22m[34mconn[0m. No error can
  possibly occur.
  
  [1m[4m[31m7.1-5 SingleHTTPRequest[0m
  
  [1m[34m> SingleHTTPRequest( [0m[22m[34mhostname, port, method, uri, header, body, target[0m[1m[34m ) [0mfunction
  [1mReturns:[0m  a record
  
  The   arguments   are   as   the   corresponding   ones   in  the  functions
  [1m[34mOpenHTTPConnection[0m   ([1m7.1-1[0m)  and  [1m[34mHTTPRequest[0m  ([1m7.1-2[0m)  respectively.  This
  function  opens  an  HTTP  connection,  tries  a  single  HTTP  request  and
  immediately   closes  the  connection  again.  The  result  is  as  for  the
  [1m[34mHTTPRequest[0m  ([1m7.1-2[0m)  function. If an error occurs during the opening of the
  connection, the [22m[32mstatuscode[0m value of the result is 0 and the error message is
  stored in the [22m[32mstatus[0m component of the result.
  
  The  previous function allows for a very simple implementation of a function
  that checks, whether your current [1mGAP[0m installation is up to date:
  
  [1m[4m[31m7.1-6 CheckForUpdates[0m
  
  [1m[34m> CheckForUpdates( [0m[22m[34m[0m[1m[34m ) ______________________________________________[0mfunction
  [1mReturns:[0m  nothing
  
  This function accesses a web page in St. Andrews and runs some [1mGAP[0m code from
  there.  This  code  knows all the currently released versions of [1mGAP[0m and its
  packages.  It prints out a summary and possibly suggests upgrades. If you do
  not  want  to  executed  code downloaded from the internet, then do not call
  this function.
  
  More         concretely,         the         page         accessed        is
  [34mhttp://www.gap-system.org/Download/upgrade.html[0m  and  the code executed is a
  single call to the function [22m[32mSuggestUpgrades[0m function in the [1mGAP[0m library.
  
