2.2 The library(http/http_client) library

The library(http/http_client) library provides more powerful access to reading HTTP resources, providing keep-alive connections, chunked transfer and conversion of the content, such as breaking down multipart data, parsing HTML, etc. The library announces itself as providing HTTP/1.1.

http_get(+URL, -Reply, +Options)

Performs a HTTP GET request on the given URL and then reads the reply using http_read_data/3. Defined options are:

connection(ConnectionType)

If close (default) a new connection is created for this request and closed after the request has completed. If 'Keep-Alive' the library checks for an open connection on the requested host and port and re-uses this connection. The connection is left open if the other party confirms the keep-alive and closed otherwise.

http_version(Major-Minor)

Indicate the HTTP protocol version used for the connection. Default is 1.1.

proxy(+Host, +Port)

Use an HTTP proxy to connect to the outside world.

proxy_authorization(+Authorization)

Send authorization to the proxy. Otherwise the same as the authorization option.

timeout(+Timeout)

If provided, set a timeout on the stream using set_stream/2. With this option if no new data arrives within Timeout seconds the stream raises an exception. This option also affects data being written by the server: if the client does not process the next block of data (4096 bytes using the default setup) within Timeout, the connection is terminated. Default is to wait forever (infinite).

user_agent(+Agent)

Defines the value of the User-Agent field of the HTTP header. Default is SWI-Prolog (http://www.swi-prolog.org).

range(+Range)

Ask for partial content. Range is a term Unit(From, To), where From is an integer and To is either an integer or the atom end. HTTP 1.1 only supports Unit = bytes. E.g., to ask for bytes 1000-1999, use the option range(bytes(1000,1999)).

request_header(Name = Value)

Add a line "Name: Value" to the HTTP request header. Both name and value are added uninspected and literally to the request header. This may be used to specify accept encodings, languages, etc. Please check the RFC2616 (HTTP) document for available fields and their meaning.

reply_header(Header)

Unify Header with a list of Name=Value pairs expressing all header fields of the reply. See http_read_request/2 for the result format.

Remaining options are passed to http_read_data/3.

http_post(+URL, +In, -Reply, +Options)

Performs a HTTP POST request on the given URL. It is equivalent to http_get/3, except for providing an input document, which is posted using http_post_data/3.

http_read_data(+Header, -Data, +Options)

Read data from an HTTP stream. Normally called from http_get/3 or http_post/4. When dealing with HTTP POST in a server this predicate can be used to retrieve the posted data. Header is the parsed header. Options is a list of Name(Value) pairs to guide the translation of the data. The following options are supported:

to(Target)

Do not try to interpret the data according to the MIME-type, but return it literally according to Target, which is one of:

stream(Output)

Append the data to the given stream, which must be a Prolog stream open for writing. This can be used to save the data in a (memory-)file, forward it to process using a pipe, etc.

atom

Return the result as an atom. Though SWI-Prolog has no limit on the size of atoms and provides atom-garbage collection, this options should be used with care.^{1Currently atom-garbage collection is activated after the creation of 10,000 atoms.}

codes

Return the page as a list of character-codes. This is especially useful for parsing it using grammar rules.

content_type(Type)

Overrule the Content-Type as provided by the HTTP reply header. Intended as a work-around for badly configured servers.

If no to(Target) option is provided the library tries the registered plug-in conversion filters. If none of these succeed it tries the built-in content-type handlers or returns the content as an atom. The builtin content filters are described below. The provided plug-ins are described in the following sections.

application/x-www-form-urlencoded

This is the default encoding mechanism for POST requests issued by a web-browser. It is broken down to a list of Name = Value terms.

Finally, if all else fails the content is returned as an atom.

http_post_data(+Data, +Stream, +ExtraHeader)

Write an HTTP POST request to Stream using data from Data and passing the additional extra headers from ExtraHeader. Data is one of:

html(+HTMLTokens)

Send an HTML token string as produced by the library library(html_write) described in section section 3.17.

xml(+XMLTerm)

Send an XML document created by passing XMLTerm to xml_write/3. The MIME type is text/xml.

xml(+Type, +XMLTerm)

As xml(XMLTerm), using the provided MIME type.

file(+File)

Send the contents of File. The MIME type is derived from the filename extension using file_mime_type/2.

file(+Type, +File)

Send the contents of File using the provided MIME type, i.e. claiming the Content-type equals Type.

codes(+Codes)

Same as string(text/plain, Codes).

codes(+Type, +Codes)

Send string (list of character codes) using the indicated MIME-type.

cgi_stream(+Stream, +Len)

Read the input from Stream which, like CGI data starts with a partial HTTP header. The fields of this header are merged with the provided ExtraHeader fields. The first Len characters of Stream are used.

form(+ListOfParameter)

Send data of the MIME type application/x-www-form-urlencoded as produced by browsers issuing a POST request from an HTML form. ListOfParameter is a list of Name=Value or Name(Value) .

form_data(+ListOfData)

Send data of the MIME type multipart/form-data as produced by browsers issuing a POST request from an HTML form using enctype multipart/form-data. This is a somewhat simplified MIME multipart/mixed encoding used by browser forms including file input fields. ListOfData is the same as for the List alternative described below. Below is an example from the SWI-Prolog Sesame interface. Repository, etc. are atoms providing the value, while the last argument provides a value from a file.

        ...,
        http_post([ protocol(http),
                    host(Host),
                    port(Port),
                    path(ActionPath)
                  ],
                  form_data([ repository = Repository,
                              dataFormat = DataFormat,
                              baseURI    = BaseURI,
                              verifyData = Verify,
                              data       = file(File)
                            ]),
                  _Reply,
                  []),
        ...,

List

If the argument is a plain list, it is sent using the MIME type multipart/mixed and packed using mime_pack/3. See mime_pack/3 for details on the argument format.

2.2.1 The MIME client plug-in

This plug-in library library(http/http_mime_plugin) breaks multipart documents that are recognised by the Content-Type: multipart/form-data or Mime-Version: 1.0 in the header into a list of Name = Value pairs. This library deals with data from web-forms using the multipart/form-data encoding as well as the FIPA agent-protocol messages.

2.2.2 The SGML client plug-in

This plug-in library library(http/http_sgml_plugin) provides a bridge between the SGML/XML/HTML parser provided by library(sgml) and the http client library. After loading this hook the following mime-types are automatically handled by the SGML parser.

text/html

Handed to library(sgml) using W3C HTML 4.0 DTD, suppressing and ignoring all HTML syntax errors. Options is passed to load_structure/3.

text/xml

Handed to library(sgml) using dialect xmlns (XML + namespaces). Options is passed to load_structure/3. In particular, dialect(xml) may be used to suppress namespace handling.

text/x-sgml

Handled to library(sgml) using dialect sgml. Options is passed to load_structure/3.